Start here
Sign in
Open the Ara web app, 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. 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:
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
-
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:
-
Choose the Ara workspace in the browser window and approve the login.
-
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:
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.
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
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.
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.
If the transcript does not explain the failure, email support@ara.so with the session URL, repository name, time and timezone, and visible error. Do not include secrets.