> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://ara.so/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://ara.so/docs/_mcp/server.
# Start here
## Sign in
Open the [Ara web app](https://ara.so/), describe your task in the homepage composer,
then select **Send** to continue with Google, GitHub, email, or SSO. The send action
also opens sign-in before you enter a task. You can also go straight to the
[sign-in page](https://ara.so/login). No local installation is required.
After signing in, choose or create a workspace. You can set up a repository and
start your first task directly in the browser.
## Choose how to use Ara
Ara exposes several interfaces over one durable session model. Choose the
interface that fits the work:
| Need | Use |
| ---------------------------------------------------------------------- | ------------------------------------------------------- |
| Start and steer tasks interactively | [Ara web app](https://ara.so/login) or editor extension |
| Work with Ara from a team conversation | Slack, connected from **Plugins** in the Ara workspace |
| Give an AI client access to Ara tools | [Ara CLI](/mcp-quickstart) |
| Integrate a service with sessions and workspace resources | [Ara REST API](/api-quickstart) |
| Let a remote Ara session use approved files and tools on your computer | Ara Device |
Ara Device is the standalone, auto-updating worker that lets an Ara session use
your Mac. It does not require a separate agent client.
Task conversation stays in a product interface such as web, an editor extension,
or Slack rather than moving into a separate terminal interface.
### Where the native agent went
The product formerly described as the **Ara native agent** is now documented as
two connected pieces: **Ara CLI** configures the local coding agent and its
direct OAuth-backed Ara MCP connection; **Ara Device** is the signed native
worker that executes approved local work. Ara web remains the conversation and
session surface. This keeps the native execution path discoverable without
creating a second transcript product.
### Connect an Ara Device
1. Open **Workspace → Devices** and select **Copy Ara CLI setup** on the **Add a
Mac** card. A dialog opens with the prompt to paste into any coding agent
with terminal access. You can also run the command yourself:
```bash
curl -fsSL https://ara.so/install.sh | bash && ~/.local/bin/ara login && ~/.local/bin/ara device
```
2. Choose the Ara workspace in the browser window and approve the login.
3. Return to **Devices** when the installer confirms the background worker is
running. The Mac appears there automatically.
To test it, open a task, type `@` in the composer, and select the Mac by name.
Ask for a harmless local check such as `Run /usr/bin/uname -m and return only
the output.` The Device stays the execution target for that task while Ara's
cloud agent handles the conversation. Re-running the install command is safe;
when macOS must reload an existing background service, Ara waits for the prior
worker to finish stopping before it starts the replacement. If macOS does not
confirm that shutdown, installation fails closed instead of starting a duplicate
worker; run the same install command again after the prior worker exits.
The worker runs as a per-user macOS background service and updates its signed,
Apple-notarized runtime and managed executor automatically. Because the CLI and
its worker are notarized (not only Developer ID signed), macOS Gatekeeper clears
them on first launch instead of warning that Apple could not verify the app. When a Device is selected for a
task, Ara's cloud agent connects it as a native execution target and runs the
task's file and shell operations through that worker. Immutable older CLI
releases use a signed compatibility bridge with the current non-extractable
native proof implementation to move onto the current update channel without
rewriting their original tags. Ara verifies the worker's
release provenance and Keychain credential boundary together before activating
an update,
including the Developer ID hardened-runtime flag and the exact approved
entitlement set. Full access covers files and tools available to that macOS
account; macOS privacy controls still apply. The native proof key uses macOS's
supported random-key API while retaining permanent Keychain storage, a
non-extractable private key, and the signed broker-only access rule. Exact
signed-package validation on a real login session covers key creation, signing,
and foreign-signer denial. The full cross-architecture proof keeps the same
assertions while allowing Rosetta subprocesses a larger completion budget.
Hosted release CI verifies the Developer ID pair,
submits it to Apple's notary service, and checks hardened broker launch on
native arm64 and x86\_64 through Rosetta, package identity, and managed-runtime
handoff. Each installed Device then health-checks
that signed pair before activation and rolls back a failed update.
## Words Ara uses
Ara uses the same names in the app, documentation, and API:
| Name | Meaning |
| ---------------- | ----------------------------------------------------------------------------------------------- |
| Task | What you ask Ara to accomplish. |
| Session | The durable conversation, work, evidence, and resulting change for a task. |
| Turn | One request and the agent work that follows inside a session. |
| Automation | A saved brief with instructions, plugins, and triggers. |
| Trigger | A schedule, event, or manual condition that starts an automation. |
| Execution | One occurrence of an automation. It creates or continues a session. |
| Workspace | Your customer or team account in Ara. |
| Repositories | The product area for connected source code, variables, plugins, and runbooks. |
| Repository | One concrete GitHub or GitLab repository. |
| Execution target | Where a session runs: Ara Cloud or an Ara Device. |
| Ara Device | A connected computer that can run Ara work locally. |
| Skill | Reusable agent instructions that Ara discovers and reads when the task calls for them. |
| Plugin | An installed capability, including an authenticated service installation, skill, or MCP server. |
The right side of a session is the **Session panel**. Its tabs are **Review**,
**Files**, **Terminal**, **Desktop**, and **Browser**. “Workspace” always means
the customer or team account; it does not mean this panel or a temporary
machine.
Inside **Review**, **Overview** keeps the pull request description, check
status, and changed files together; **Discussion** and **Commits** remain
focused tabs.
Below the session composer, a separate row shows the working branch, which you
can click to copy, and where the session runs.
The **Session summary** button in the session header lists the execution target,
subagents, and side tasks. On a wide window it opens beside the
transcript; on a narrow one it opens over it.
## Manage in-app notifications
Task completions, confirmations, and errors group into one expandable in-app
notification stack. Dismiss one notice with its visible **X**, or select **Turn
off notifications** to mute completion and confirmation notices. Actionable
errors remain visible. Re-enable notices later from **Preferences → Feedback →
In-app notifications**. Browser notifications remain a separate choice.
## Set up a repository
Do this before the first task on a repository.
### Connect the repository
Open **Repositories**. Connect GitHub or GitLab, grant access only to the repositories
Ara should use, then select the repository.
The repository detail header keeps its path and actions together: use **Edit**
to return to the editable Setup section, or open the three-dot menu for setup
analysis and the Ara CLI setup prompt.
### Add variables and plugins
Open the repository. Add its repository-scoped variables first, then configure
each required plugin. Values are encrypted, write-only, and keyed to the stable
repository connection rather than a display path.
From the Repositories list, select **Setup** beside a repository to copy
a guided setup prompt into your preferred coding environment. The prompt
helps the coding agent prepare the runtime and browser tooling Ara needs for
visual walkthroughs and before-and-after review images. The setup card is labeled
**View Demos not Diffs** and places cursor indicators over both examples to make
the visual outcome clear.
* Keep credentials scoped to the repository or workspace that needs them.
* Values are encrypted and write-only after saving.
* Never paste a secret into a task or documentation.
### Keep setup repository-native
Store the operating guide in `.ara/runbook.md`. It should contain the verified
setup, development, test, and validation commands a new session needs. Ara reads
that file directly from the repository. When `ara_runbook_update` proposes a
change, it does so through a branch and pull or merge request, so the same review
and history rules apply as any other code change.
Checkout, fetch, and workspace preparation happen automatically when Hands
attaches. Any internal caching that makes this faster remains invisible.
## Start a task
Open **New Task**, choose the prepared repository, and describe a bounded result
with checks that prove it is done.
```text
Fix the flaky test in src/auth/session.test.ts.
Reproduce the failure, keep public behavior unchanged, add a regression case,
run the focused test file, and open a pull request.
```
Follow the session and add a reply when Ara needs another constraint,
credential, file, or verification step.
### Models and inference security
Ara's managed inference service uses the curated models shown in the task
composer. Customer model API keys are not copied into a task.
Each session receives one short-lived capability limited to the exact session,
model, route, and price version. It sends that capability to `api.ara.so`; only
the API process can call the selected aggregation route. Reusable gateway and
provider keys never enter a sandbox, environment variable, transcript, artifact,
browser, or command line. A grant binds one route for the whole request, so a
live request never switches gateways.
Before generation, Ara atomically reserves the request against the workspace's
remaining shared credit balance. There are no separate request, run, user-day,
workspace-day, or global-day dollar caps. If the full requested output does not
fit, Ara lowers the output ceiling to what the remaining credit can afford
instead of stranding a small balance. Request size in bytes is only a transport
and memory bound—it is never converted into tokens or dollars. A long
history uses provider-reported context usage plus the semantic content appended
after it, bounded from decoded UTF-8 content rather than request-body bytes, so
JSON escaping and repeated history cannot become a hidden financial ceiling.
Terminal provider usage creates the customer debit at Ara's published model
price in the same database transaction as settlement. The route's own evidence
then verifies the serving provider, concrete model, BYOK-versus-system
credential type, tokens, and provider cost. The customer charge does not change
during this reconciliation. Ambiguous requests retain their exposure hold and
never create a guessed customer charge.
Included and purchased workspace credits are one pool: model usage and sandbox
minutes draw from the same balance. Ara leases each billable sandbox minute
before it starts and settles the rounded actual runtime, so concurrent model and
sandbox work cannot overspend the workspace balance. Operational concurrency,
rollout controls, and emergency breakers remain, but they are not additional
spending limits.
A model-provider error or network interruption fails visibly. Ara never silently
switches the task to another harness or model. Operators can stop all new
inference, one credential, route, or model without a deployment, and can roll a
canary back by deployment version.
Ara classifies an interrupted response by what caused it rather than by whichever
internal signal happens to observe it first, so cancelling a task is treated as
the ordinary event it is and never suspends inference for other sessions.
What Ara records about a request is operational metadata only: the request and
upstream request identifiers, the reported model, whether an Ara-owned provider
key or the gateway's own credit served it, the upstream HTTP status, a bounded
failure code, token and cache counters, any provider-side search or fetch counts,
the serving region and service tier, and how long the upstream took to answer,
to emit its first event, and to finish streaming. Prompts, completions, tool
payloads, images, and credentials are never recorded, and a raw provider error
body is never stored. Where the concrete serving provider is not stated by the
route, Ara records how the attribution was derived rather than presenting a
guess as fact.
When Ara declines a provider-hosted capability, it records only the closed
capability category and protocol signal so the mismatch can be corrected
without inspecting your prompt or tool contents. Tool names, descriptions,
schemas, URLs, and inline media bytes are never recorded.
Ara permits a closed set of tool types that run inside its own sandbox and refuses
work the model provider would perform and bill for separately: provider-hosted
search, code execution, file or image tools, remote tool servers, and requests
to fetch remote media. The contents of local tool schemas and descriptions are
not interpreted as hosted capabilities. A structurally bounded, static inline
PNG returned by a local tool can continue to the model after Ara verifies its
wire envelope and bounded decoded size; it stays inside the request envelope and
does not ask the provider to fetch anything. Other media, including audio, and
remote references remain blocked. Provider-hosted search or media tools remain
blocked from Ara-paid requests.
The inference tables are inaccessible to application roles. Narrow,
service-role-only database functions authorize grants, reserve spend, settle
usage, project normal billing, and reconcile Gateway generations atomically.
Repository and workspace secrets remain available only for the tools and
services you configure. Saving a variable named like a model-provider credential
is rejected; it cannot shadow API-owned inference authority.
### Provider keys
Open **Settings → Models & credentials**. The **Providers** card lists Ara-hosted
inference first, then every provider your workspace has connected, each row
naming how it authenticates. Free workspaces run connected-provider models;
open the menu on the **Ara** row and choose **Upgrade** to subscribe to Ara-hosted
inference in Billing.
Each connected row is marked with a green pill naming the workspace member who
connected it, so it is clear whose subscription or key a run will spend rather
than only that something is connected.
Choose **Connect** beneath the provider rows to browse every
model provider the Ara runtime knows about — including Anthropic, OpenAI,
Google, Azure, Amazon Bedrock, Groq, Mistral, OpenRouter, Together, and the rest
of the runtime's provider list — grouped by whether the provider takes an API
key or a subscription sign-in. The list always shows the full catalog, including
providers already connected, because a workspace can pool several accounts of the
same provider; a provider already in use shows who connected it. Workspace owners and admins can save an API key
for any provider that accepts one, along with the non-secret settings that
provider needs, such as a Cloudflare account ID or a Vertex project and location.
A saved key is encrypted before it is stored and is never returned to the
browser, an API response, a log line, or an audit entry: the page shows only
whether a provider is connected, how it authenticates, and which settings are
configured. Removing a provider deletes the stored credential.
Providers that offer a sign-in in the runtime catalog — currently including
OpenAI, Anthropic, GitHub Copilot, Kimi For Coding, OpenRouter, Radius,
and xAI — connect through the provider's own flow instead of a pasted key.
Depending on the provider, you follow a sign-in link, enter a short device code
on its activation page, or paste the code it hands back after you approve
access. The resulting credential is encrypted and stored exactly like a saved
key, shows as **Subscription** on the provider's row, and is refreshed
automatically; it can be renewed with **Sign in again** or removed at any time.
A provider that supports both methods appears under both Subscription and API
when connecting, because a subscription and an API key are different accounts
at the same provider.
Each connected provider also becomes its own category in the session model
menu, named for the provider and how it authenticates — for example **OpenAI ·
API key** or **OpenRouter · API key** — holding every model that provider
serves. Each category carries the provider's mark badged with the avatar of the
member who connected it, so choosing a model shows whose account it runs on.
Below the Providers card, the **Model router** section chooses one connected
provider and then that provider's model for each of three slots: one model for **Thinking** (deep reasoning), one for **Coding**
(everyday session work), and one for **Subagent** (delegated, read-only
investigation). A subagent runs on the Subagent model unless the agent asks for
a different slot; it can name a slot but never a model, so a delegated run can
never move itself onto a provider or price you did not configure.
Which account pays follows from the model itself, not from the slot it was
picked through: a model served by one of your own connected providers is billed
to you by that provider, and an Ara model is billed as Ara inference. A slot is
only a label pointing at a model, so pointing a slot at a different model moves
the billing with it, and the two can never disagree.
The **Models** card below lists Ara's included models followed by every model
your connected providers serve, each row led by its provider's mark and carrying
the thinking-level control. Because a single provider can serve hundreds of
models, the card is searchable: type to filter by model name, model id, or
provider.
Picking one of those models runs the session on your own credential: the
provider call is made with your stored key, so those tokens are billed to you by
the provider and are not charged as Ara inference. Sandbox and tool time is
still metered by Ara as usual. Ara's own models keep running on Ara-included
inference and are unaffected.
A session pinned to a provider model never quietly falls back to Ara. The
selection survives a reload and every following turn, including after the
provider is disconnected — the model stays named in the composer instead of being
swapped for an Ara model behind your back. If the provider is disconnected after
the session was created, or the credential is rejected, expired, or rate-limited
by the provider, the run fails and says so; reconnect the provider in
**Settings → Models & credentials**, or pick an Ara model instead.
Sessions running on your own provider are named the same way as any other
session, from your first message, without spending your provider tokens on the
title.
## Plugins and skills
Open **Plugins** to inspect every reusable capability in one place. A package
with a remote MCP component uses the MCP icon; a skills-only package uses the
skills icon. Personal, team, Ara, marketplace, and repository-owned skills stay
separate under **Your skills**, so their owner and edit permissions remain clear.
Ara recognizes the portable [Agent Plugins 1.0](https://agent-plugins.org/)
layout when a package has a validated root `plugin.json`, optional `mcp.json`,
and `skills/*/SKILL.md` components. MCP authentication, OAuth grants, secrets,
and runtime policy remain Ara-managed: a package manifest never executes a hook
or arbitrary command. Packages that only publish a skills bundle are labelled
as such rather than being presented as a conformant Agent Plugin.
Agents may inspect a package's compact declared skill inventory through Ara
MCP. The full skill bundle is materialized only after the owning MCP connection
is active.
During an independent web and API deployment, the existing skills catalog stays
available even if package metadata has not reached the API yet. Package cards
appear as soon as that optional metadata endpoint is ready.
Enabled plugin skills become available when that plugin is selected for the
task. Repository-owned skills in `.agents/skills` travel with the repository.
Ara gives the agent the enabled skill catalog at the start of each turn. It sees
each skill's name and description first, then reads its complete `SKILL.md` only
when the request calls for it. This keeps a large skill library available without
putting every instruction into every prompt.
Choose a workspace skill from the `/` menu when you want to invoke it explicitly.
You can also type the `$skill-name` form in agent apps that support it.
Otherwise, write the task normally and Ara can select a relevant skill from its
description. Keep skill descriptions specific enough to distinguish when the
skill should and should not run.
## Sessions
A session keeps the prompt, conversation, commands, changed files, checks, and
pull request together. Steer the same session when correcting the same task;
start a new one only for a separate outcome.
Before accepting a result, check:
* changed files and the final diff
* commands and test results
* screenshots or other evidence
* the pull request or merge request
### Who else is here
Teammates using Ara at the same time appear next to your own avatar at the
bottom of the sidebar. Select one to go to them: you land in their session, and
if they have the side panel open on a tab such as **Review** or **Terminal**,
yours opens on the same tab so you see what they see. Above three teammates the
avatars become a single button that opens a searchable list.
Inside a session you also see, live:
* their **cursor**, moving over whichever area they are reading
* anything they **highlight**, shown in their own color
* whether they are **typing** a message, above the composer
Each teammate appears once, however many tabs they have open: you see whichever
tab they are actually working in. Your own tabs are never shown back to you.
Presence is live only while someone is looking at the session, and it records
nothing. Close the tab and everything disappears for everyone else. Message
drafts are never shared — you can see that someone is typing, never what they
have written.
## Automations
Prove a task in a manual session before automating it. Choose a prepared
repository, reuse the tested prompt, select a schedule or event, and review the
first executions.
Open **Automations** to see built-in and custom automations in one compact list.
Use **Created by me** to focus on custom automations, and search to narrow the
list. Custom automations are ordered with the active ones first and the paused
ones at the bottom. Select **Create automation**, then choose one of these
starting points:
* **Start from a template** for a ready-made workflow you can customize.
* **Create from a session** to turn proven work into a repeatable automation.
* **Start from scratch** to define the instructions yourself.
During setup, choose the repository, add schedule or event triggers, and enable
the plugins and MCP servers the automation may use. Open an automation from the
list to edit those settings, pause it, or inspect its execution history.
For a Slack event feed, use its event-behavior selector to choose whether Ara
runs automatically, only runs when mentioned, or posts the event without
starting a run.
Event triggers act only on the activity they are for. A pull request review
automation responds to a pull request being opened, reopened, marked ready for
review, or updated with new commits; editing a title or description, toggling
auto-merge, or pushing to a draft does not start an execution. Likewise, issue
and comment triggers that listen for Ara respond only when the issue or comment
actually addresses Ara. Skipping the rest is expected behavior, not a missed
event.
**Automation activity** groups every execution by month in the same compact audit-log format. Select a row to open the session
behind it.
Start with reporting or draft changes. Enable unattended mutation or merge only
after the prompt and guardrails are reliable.
## Trials and billing
Open **Dashboard** in the sidebar to see the workspace's usage, credits and
current plan. It is the same view as the Dashboard row inside Settings.
A trial can require a payment method even when nothing is charged up front. Ara
limits trial redemption by user and workspace, and also checks for the same card
being reused across otherwise separate accounts. Repeated redemption that looks
abusive can be blocked or have the trial canceled. If a legitimate team shares a
company card and gets stopped, contact [support@ara.so](mailto:support@ara.so).
Cancelling a trial returns the workspace to the Free plan immediately. If you
change your mind before the trial period ends, upgrade to the same plan again
and the remaining trial resumes where it left off; no new trial is consumed and
nothing extra is charged.
## Code review
Open **Automations**, choose **PR Review**, and select the repositories it
should watch.
* **Review bot** posts findings for a human to resolve.
* **PR Merge Bot** evaluates Ara-authored changes against CI, verification,
accepted risk, and human-approval requirements before merging.
Start with review comments. Turn on unattended merge only after the repository's
requirements are explicit and consistently enforced.
## Troubleshooting
Start with the session transcript. It normally shows whether the failure is
repository access, setup, a missing credential, model access, billing, or the
task itself.
If a session felt slow to reply rather than failing, include the session URL and
roughly when it happened. Ara records the model and reasoning effort each turn
ran with alongside its response timing, so support can tell a slow model
response apart from slow setup without asking you to reproduce it.
| Problem | Check |
| --------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Session will not start | Repository access, model availability, workspace usage, then unfinished uploads. |
| Setup or tests fail | Check `.ara/runbook.md`, then run the smallest failing command in the session. |
| Credential is missing | **Repositories → Variables**. Add it there, never in the transcript. |
| Task is going the wrong way | Reply in the same session with the missing constraint and what must remain unchanged. |
| No pull request opened | Repository write access, whether a diff exists, required checks, and the delivery error in the transcript. |
If the transcript does not explain the failure, email
[support@ara.so](mailto:support@ara.so) with the session URL, repository name,
time and timezone, and visible error. Do not include secrets.