# Claude Code (/docs/agents/claude-code) Claude Code is installed in the standard Adria sandbox image. Choose the credential supported by your Anthropic account. ## Connect an API key [#connect-an-api-key] ```sh title="Local terminal" cube auth claude ``` Paste your Anthropic API key at the hidden prompt. Model usage is billed by Anthropic. ## Use a setup token [#use-a-setup-token] If your Claude account supports setup tokens, run `claude setup-token` on your local computer, then: ```sh title="Local terminal" cube auth claude --method setup_token ``` Paste the token when prompted. This is separate from importing local configuration; login caches are not imported. ## Run Claude Code [#run-claude-code] ```sh title="Local terminal" cube start feature/payments --tmux claude ``` Inside the sandbox: ```sh title="Sandbox terminal" claude ``` Claude works in the remote repository with the sandbox's tools and services. Its own permission settings govern tool approvals. Use the [remote browser](/docs/computer-use) on desktop-enabled images to inspect an app. ## Optional: bring your setup [#optional-bring-your-setup] Reuse your local instructions, settings, skills, and MCP definitions with [configuration imports](/docs/agents/configuration). Preview the import first; credentials and subscription login sessions are managed separately. ## Replace a credential [#replace-a-credential] Run the same authentication command again to replace the stored credential. Use `cube auth claude --remove` to disable future delivery. Already running agents may retain it; revoke it with Anthropic if it must be invalidated. # Codex (/docs/agents/codex) Codex is installed in the standard Adria sandbox image. Configure its credential locally, then launch it inside a sandbox. ## Connect your credential [#connect-your-credential] ```sh title="Local terminal" cube auth codex ``` Paste your OpenAI API key when prompted. The terminal hides the credential. API usage is billed by OpenAI; importing local settings does not import a ChatGPT subscription login. ## Start a task [#start-a-task] ```sh title="Local terminal" cube start feature/payments --tmux codex ``` Then launch the agent in the remote checkout: ```sh title="Sandbox terminal" codex ``` Give Codex a task, such as adding validation to a form and running the existing tests. Review its changes with your normal Git workflow. ## Optional: bring your setup [#optional-bring-your-setup] Reuse your local instructions, settings, skills, and MCP definitions with [configuration imports](/docs/agents/configuration). Preview the import first; credentials and subscription login sessions are managed separately. ## Return to your work [#return-to-your-work] Detach with **Ctrl+B**, then **D**. Reconnect using `cube connect feature/payments --tmux codex` while the VM is running. Pausing stops Codex and preserves its files; resume the sandbox and launch Codex again. Use [agent status](/docs/logs) to inspect recent activity across Sessions. # Coding agents (/docs/agents/coding-agents) Adria provides the computer where your agent works. The standard image includes Codex, Claude Code, and Pi. Connect the agents you use once from your local computer, then launch them in any of your sandboxes. Personal configuration imports are optional. ## Connect an agent [#connect-an-agent] After `cube login`, run the relevant command **locally**: | Agent | Command | Credential | | ------------------------------ | --------------------------------------- | --------------------------------- | | Codex | `cube auth codex` | OpenAI API key | | Claude Code | `cube auth claude` | Anthropic API key | | Claude Code with a setup token | `cube auth claude --method setup_token` | Output of `claude setup-token` | | Pi | `cube auth pi --provider anthropic` | API key for the selected provider | The command prompts for the credential with terminal echo disabled. For Pi, choose the provider you use, such as `anthropic`, `openai`, or `google`. Check stored configuration with: ```sh cube auth ``` This reports whether credentials are configured, not whether they have remaining credit. API keys use the model provider's API billing. Importing settings does not import subscription login sessions or convert a subscription into API credit. ## Launch in a sandbox [#launch-in-a-sandbox] **Local:** connect to a persistent agent terminal: ```sh cube connect feature/payments --tmux agent ``` **Sandbox:** launch your configured agent: ```sh codex # Or: claude # Or: pi ``` The agent works in the sandbox's repository and can use its build tools and services. Detach with `Ctrl+B`, then `D`; reconnect with the same local command. For independent tasks, [use separate sandboxes](/docs/parallel-engineering). ## Optional: bring your settings and skills [#optional-bring-your-settings-and-skills] Import your local setup if you want the remote agent to use your personal instructions, skills, MCP tools, or extensions. This is separate from credentials. Follow [Bring your agent setup](/docs/agents/configuration) to preview and save it. Project configuration committed to Git already arrives with your repository. ## Replace or remove credentials [#replace-or-remove-credentials] Run the same `cube auth ` command again to replace a credential. New agent launches use the new value. To disable future credential delivery: ```sh cube auth codex --remove ``` Already running agents can retain credentials in memory. Revoke a credential with its provider if you need to invalidate it. `cube logout` revokes the local Adria login and preserves centrally configured agent credentials. Remove a saved configuration import separately: ```sh cube config remove codex ``` # Bring your agent setup (/docs/agents/configuration) Your agent can run with its default setup. If you want your personal instructions, skills, or MCP tools on every computer, import them once from your local machine. This is separate from [agent credentials](/docs/agents/coding-agents) and [repository environment files](/docs/environment-variables). ## Preview an import [#preview-an-import] Run the import on your local computer: ```sh title="Local terminal" cube config import codex --dry-run ``` Replace `codex` with `claude` or `pi`. Review the selected files before uploading. Settings can include secrets, executable hooks, and tools that run code. ## Upload and check readiness [#upload-and-check-readiness] ```sh title="Local terminal" cube config import codex --wait cube config status ``` `--wait` waits for cloud acceptance. Resource preparation may continue after the command returns; check status until the import is `ready`. Without `--wait`, the command queues a local upload and returns immediately. A locally queued import is not yet available in a sandbox. ## What is included [#what-is-included] Supported imports include personal settings, instructions, MCP definitions, skills, and selected plugins or extensions for the agent. Conversation history and login caches are excluded. A configured MCP server may still need its own dependencies, network access, or authentication inside the sandbox. An imported definition does not grant access to an external service by itself. ## When changes take effect [#when-changes-take-effect] New Sessions prepare saved configuration before reporting readiness. Existing Sessions apply changed imports on subsequent agent launches. Import again after changing your local settings. This is not continuous file synchronization. Project-level files checked into the repository arrive through the normal Git checkout. ## Remove an import [#remove-an-import] ```sh title="Local terminal" cube config remove codex ``` Removing a configuration import is separate from removing an agent credential. Use `cube auth codex --remove` to disable future credential delivery. # Agents on Adria (/docs/agents) Use the coding agent you already know. Adria gives it a remote computer with your repository, development tools, and services. ## Bring your coding agent [#bring-your-coding-agent] Codex, Claude Code, and Pi are included in the standard sandbox image. Connect your credentials once, then launch the agent in any of your computers. Importing your personal settings and skills is optional. Run Codex with your OpenAI API key and personal configuration. Connect an API key or setup token and bring your Claude setup. Choose your model provider and run Pi in a sandbox. Import instructions, MCP definitions, skills, and supported extensions. Your chosen agent controls its own conversation, tools, and approval behavior. Adria supplies the environment and configured credentials. Read [coding agent authentication](/docs/agents/coding-agents) for credential management. ## Optional: automate documentation updates [#optional-automate-documentation-updates] Dashboard workflows are separate from running your own coding agent. You do not need GitHub indexing, a Notion integration, or a workflow to start a computer. Adria's built-in workflow experience connects GitHub changes to your documentation. The current workflow reviews pull requests merged into `main`, identifies architecture changes, and proposes Notion updates, including a C4 diagram. You author the workflow in natural language, choose its repository and Notion scope, then review page proposals before they are applied. Connect your sources and preview a workflow before activating it. Inspect evidence, approve proposals, and follow the run history. ## Work on independent tasks [#work-on-independent-tasks] Use [one sandbox per branch](/docs/parallel-engineering) when agents should work independently. Terminals inside one Session share the same repository and processes; they are useful for collaboration on the same task. # Pi (/docs/agents/pi) Pi is included in the standard Adria sandbox image. Configure a provider credential locally, then start Pi in your remote repository. ## Choose a provider [#choose-a-provider] ```sh title="Local terminal" cube auth pi --provider anthropic ``` Use `openai` or `google` instead if that is your provider. Paste the matching API key at the hidden prompt. Model usage is billed by your chosen provider. ## Launch Pi [#launch-pi] ```sh title="Local terminal" cube start feature/payments --tmux pi ``` Inside the sandbox: ```sh title="Sandbox terminal" pi ``` Use the model and provider configured for your Pi setup. Project dependencies and services run on the same sandbox computer. ## Optional: bring your setup [#optional-bring-your-setup] Reuse your local instructions, settings, skills, and MCP definitions with [configuration imports](/docs/agents/configuration). Preview the import first; credentials and subscription login sessions are managed separately. ## Keep tasks independent [#keep-tasks-independent] Run separate tasks in [separate branch sandboxes](/docs/parallel-engineering). To reconnect to a running Pi terminal, use `cube connect feature/payments --tmux pi`. After a pause, restart Pi and any services your task needs. # Review agent work (/docs/agents/reviewing-work) Each workflow run records its status, workflow version, evidence, and page proposals. Open the run from the workflow's run history. ## Inspect the evidence [#inspect-the-evidence] Review the architecture-change decision and its rationale. Follow the cited repository files and documentation pages to check the context used by the agent. When a run proposes a C4 diagram, review the Mermaid content alongside the documentation changes. A successful analysis does not automatically mean that every proposal should be accepted. ## Approve or reject a proposal [#approve-or-reject-a-proposal] Proposals can create a page or update an existing one. Review them individually, then approve or reject each page proposal. Approval allows that proposal to be applied to Notion. Rejection keeps it from being applied. Mixed decisions can leave a run partially applied. ## Understand run states [#understand-run-states] | State | What is happening | | --------------------- | ------------------------------------------------------ | | Queued | The run is waiting to be processed | | Analyzing | Adria is evaluating the change and preparing proposals | | Awaiting approval | Proposals are ready for review | | Applying | Approved proposals are being written | | Succeeded | The run finished successfully | | Partially applied | Only part of the proposed work was applied | | Failed or interrupted | The run did not finish normally | ## Handle conflicts [#handle-conflicts] An update proposal records the Notion revision it was based on. If the page changes before application, a conflict can prevent the stale proposal from overwriting newer content. Review the current page and the proposed changes before retrying. Use the dashboard's retry controls for failed runs or failed application attempts. ## Keep a record [#keep-a-record] Run history links outcomes to the workflow version and originating change. When behavior needs adjusting, edit the workflow's instructions or scope, preview the new version, and review later runs against that definition. # Create an Adria workflow (/docs/agents/workflows) Create workflows in the dashboard's **Workflows** page. The current workflow reviews pull requests merged into `main` and proposes architecture updates in Notion, including a C4 Mermaid diagram. ## Connect your sources [#connect-your-sources] Before creating a workflow: 1. [Install the Adria GitHub App](/docs/platform/github) for the repositories you want to monitor. 2. [Connect Notion](/docs/platform/notion) and share your architecture documentation with the integration. 3. Wait for the repositories and pages to be indexed so they appear in the workflow resource selectors. ## Describe the workflow [#describe-the-workflow] Enter an instruction such as: > When a pull request is merged, determine whether architecture changed. If it > did, propose updates to the C4 Mermaid diagram and relevant architecture > documentation in Notion. Select the GitHub source and repositories, the Notion source, and the architecture root page. That scope determines which repositories are monitored and where documentation proposals belong. ## Preview and save [#preview-and-save] Choose **Preview workflow** to inspect the generated definition. Check the trigger, selected repositories, Notion destination, and proposed behavior. Save the workflow as a draft, or activate it when the definition is ready. Drafts do not process repository events. ## Activate and pause [#activate-and-pause] An active workflow can create runs when a selected repository's pull request is merged into `main`. Pause it to stop new event-triggered work without deleting the definition. Editing a workflow creates a new version. Run history retains the version used for each run, so you can understand which instructions produced a proposal. ## Review the result [#review-the-result] Open a run to inspect its reasoning, cited files and pages, and individual page proposals. The workflow proposes changes for approval; it does not silently rewrite your documentation. Continue with [reviewing agent work](/docs/agents/reviewing-work). # CLI reference (/docs/cli) Run Adria commands on your local computer unless a guide says otherwise. Start with [Get started quickly](/docs/quickstart) to install the CLI and sign in. ```sh cube --help cube start --help cube --version ``` Use `--help` on any command for all options supported by your installed version. ## Account and repository [#account-and-repository] | Command | Purpose | | ------------------------- | ----------------------------------------------------- | | `cube login` | Sign in and authorize GitHub through a browser | | `cube login --no-browser` | Sign in with a URL and one-time completion code | | `cube logout` | Revoke and remove this local Adria login | | `cube auth` | Show GitHub and agent credential configuration | | `cube auth github` | Connect or renew GitHub authorization | | `cube init` | Identify the local GitHub repository in Adria | | `cube init --json` | Print repository identity and local Git state as JSON | ## Sandbox lifecycle [#sandbox-lifecycle] `` means a branch name or Session UUID. Use UUIDs outside a repository or when branch names are ambiguous. | Command | Purpose | | ----------------------------------- | --------------------------------------------------- | | `cube start ` | Create or resume a Session and enter its shell | | `cube connect ` | Connect to an existing Session, resuming if paused | | `cube sessions` | List your Sessions; alias: `cube ls` | | `cube sessions --json` | Print Sessions as JSON | | `cube pause ` | Stop compute and preserve disk | | `cube kill ` | Permanently delete a Session and its disk | | `cube usage --detailed` | Show monthly VM time and estimated cost per Session | Pause and kill return when their request is accepted. Check completion with `cube sessions`. `cube kill --all` deletes all your Sessions and disks across repositories; use a single Session target to remove only one task. ## Start and connect options [#start-and-connect-options] | Option | Purpose | | ----------------------------- | -------------------------------------------------------------------- | | `--source-ref origin/release` | Choose the starting remote ref for a new branch (`start` only) | | `--tmux work` | Create or attach a named remote tmux terminal | | `--command 'git status'` | Run a remote command without a PTY | | `--tty` | Allocate a PTY for `--command` | | `--terminal current` | Use the current terminal; choices: `auto`, `current`, `cmux`, `tmux` | | `--diagnostics` | Print Session details and startup timings | | `--timeout 30m` | Set the readiness wait; default: `20m` | | `--ssh-config` | Write a five-minute OpenSSH config and print its path | Run a command directly from your local terminal: ```sh cube connect feature/payments --command 'git status --short' ``` Commands execute in the remote repository. `--tmux` requires an interactive shell and cannot be combined with `--command`. Remote commands are not automatically replayed after connection loss. ## Activity and capture [#activity-and-capture] | Command | Purpose | | ------------------------------------- | ------------------------------------------------------------ | | `cube sessions --json` | Show VM lifecycle and individual terminal agent observations | | `cube sessions capture off` | Disable terminal capture for the Session | | `cube sessions capture on` | Enable terminal capture on supported images | Capture records terminal input and output and is enabled by default on supported images. Turning it off stops future collection and does not delete existing data. See [logs and agent status](/docs/logs) for observed state and capture behavior. ## SSH and file transfer [#ssh-and-file-transfer] `cube connect --ssh-config` prints the path of a temporary OpenSSH config. Use it with `ssh -F`, `scp -F`, or `sftp -F`. The access grant expires after five minutes. See [SSH and terminals](/docs/ssh) and [File operations](/docs/files) for complete examples. `start` and `connect` also accept OpenSSH forwarding options `-L`, `-R`, and `-D`. ## Repository environment files [#repository-environment-files] Run these commands from your local repository. Saved files are reused by new and resumed computers; use `apply` to refresh a running one. | Command | Purpose | | ---------------------------------------- | -------------------------------------------------- | | `cube env import` | Select and save local environment files | | `cube env import apps/api/.env` | Save a specific repository environment file | | `cube env import --dry-run` | Preview file paths and key names without uploading | | `cube env import --shared apps/api/.env` | Publish team defaults with GitHub write access | | `cube env list` | Show saved paths, key names, and scopes | | `cube env apply ` | Refresh environment files in a running computer | | `cube env remove apps/api/.env` | Remove personal values for that file | Personal values override shared defaults. Restart your applications after applying changes. See [Environment variables](/docs/environment-variables) for updates, conflicts, and shared configuration. ## Agent setup [#agent-setup] | Command | Purpose | | --------------------------------------- | -------------------------------------------------- | | `cube auth codex` | Save an OpenAI API key for Codex | | `cube auth claude` | Save an Anthropic API key for Claude Code | | `cube auth claude --method setup_token` | Save a Claude setup token | | `cube auth pi --provider anthropic` | Save Pi credentials for a selected provider | | `cube auth codex --remove` | Disable future delivery of this agent's credential | | `cube config import codex --dry-run` | Preview settings and resources to import | | `cube config import codex --wait` | Import and wait for cloud acceptance | | `cube config status` | Check import progress and readiness | | `cube config remove codex` | Remove the saved configuration import | Replace `codex` with `claude` or `pi` for their config commands. See [Coding agents](/docs/agents) for the difference between credentials and settings. ## Ports and desktop [#ports-and-desktop] | Command | Purpose | | -------------------------------------------------------- | ------------------------------------------------ | | `cube open 3000 --session ` | Forward an app and open it in your local browser | | `cube forward 3000:8080 --session ` | Forward remote port 3000 to local port 8080 | | `cube desktop ` | Open a supported sandbox's desktop viewer | | `cube browser ` | Open a URL in the sandbox's browser | | `cube computer screenshot --output screen.png` | Save a desktop screenshot | Port tunnels need a ready Session and stay active while their command runs. Desktop commands require an image with desktop support. See [Networking and tunnels](/docs/networking) and [Computer use](/docs/computer-use). ## Updates [#updates] Update your installed CLI: ```sh cube update ``` Set `NO_COLOR=1` to disable terminal colors; use the commands' JSON flags where available for machine-readable output. # Commands and processes (/docs/commands) Run commands in an interactive remote shell, or send a command directly from your local terminal. Commands execute in the sandbox's repository directory and use its installed tools and environment. ## Run a command from your computer [#run-a-command-from-your-computer] **Local:** ```sh cube connect feature/payments --command 'git status --short' ``` `connect` selects an existing Session, resumes it if paused, and waits for readiness. The command's output appears in your local terminal, and its exit code passes through the CLI. Quote the remote command so your local shell does not expand its variables or operators. For example, in a Bun repository: ```sh cube connect feature/payments --command 'bun install && bun test' ``` An explicit `--command` is not automatically replayed after a connection loss. Inspect the result before deciding whether to run it again. ## Run an interactive process [#run-an-interactive-process] Open a shell and use the repository normally: ```sh cube connect feature/payments ``` For a command that needs a terminal, add `--tty`: ```sh cube connect feature/payments --tty --command codex ``` [Configure the agent](/docs/agents) first. Use a persistent named terminal for an agent or service you want to detach from and revisit. ## Keep a service running [#keep-a-service-running] **Local:** create a named remote terminal: ```sh cube connect feature/payments --tmux web ``` **Sandbox:** start your project's development server. For a Bun project with a `dev` script: ```sh bun run dev ``` Detach with `Ctrl+B`, then `D`. The process keeps running while the VM runs. Reconnect with the same `--tmux web` command to see output or stop the process with `Ctrl+C`. Different tmux names give you separate terminals in the same VM. Use [networking and tunnels](/docs/networking) to open the application locally. For container services, see [Run Docker](/docs/docker). ## Process lifetime [#process-lifetime] A local disconnect and a VM pause have different effects. Persistent terminals survive a disconnect while the VM keeps running. Pausing the Session stops its processes; after resume, restart your agents, servers, and tests as needed. See [SSH and terminals](/docs/ssh) for interactive connection recovery and [Lifecycle](/docs/lifecycle) for disk persistence. # Computer use (/docs/computer-use) Desktop commands require a Session image with desktop support enabled for your environment. Updating the CLI alone does not add desktop tools to an existing sandbox. A Session without them reports `desktop_not_installed`. ## Choose where the browser runs [#choose-where-the-browser-runs] | Command | Browser location | Use it for | | ----------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------- | | `cube open 3000 --session feature/payments` | Your computer | Previewing a forwarded app in your normal browser | | `cube browser feature/payments http://localhost:3000` | The sandbox | Interacting with the app using remote Chromium | | `cube desktop feature/payments` | Viewer on your computer, desktop in the sandbox | Watching or controlling the remote desktop | The remote browser shares the sandbox's files. `localhost` in its URL refers to the sandbox, so it can reach the development server running there. ## Open the remote browser [#open-the-remote-browser] Start your application inside the sandbox, then run **locally**: ```sh cube browser feature/payments http://localhost:3000 ``` Adria opens Chromium inside the sandbox and shows the desktop through a local viewer URL. To view the desktop without choosing a browser URL: ```sh cube desktop feature/payments ``` These commands require an existing Session and can resume a paused one. They return your terminal prompt while a local helper keeps the viewer connected. Use `--no-open` to print the viewer URL without opening it automatically. ## Observe and interact [#observe-and-interact] Run these commands **locally**, with the Session explicitly selected: ```sh cube computer screenshot feature/payments --output screen.png cube computer click feature/payments --x 420 --y 280 cube computer type feature/payments 'Hello from Adria' cube computer key feature/payments Return cube computer scroll feature/payments --direction down --amount 3 ``` Screenshots are 1920 × 1080 PNGs saved to the requested path. Click coordinates use screenshot pixels with the origin at the top left. `type` pastes text into the focused application; `key` sends a key or chord such as `CTRL+L`. Scroll amounts are wheel ticks. Screenshot and input commands require a ready Session. Use its UUID outside a repository or when a branch name is ambiguous. Independent headless Playwright processes do not automatically appear in this shared desktop. ## Share control with an agent [#share-control-with-an-agent] The viewer starts in watch mode. Select **Take control** to use the desktop yourself. While you hold control, Adria computer input commands from agents are blocked; screenshots remain available. Select **Return control** to let the agent send input again. ## Close and reconnect [#close-and-reconnect] Closing the viewer leaves the remote desktop and browser running while the VM runs. After a lost connection, rerun `cube desktop ` to reconnect. Pausing preserves the browser profile on disk, but not tabs or process memory. After resume, restart your app and open the browser again. # Run Docker (/docs/docker) The standard Adria image includes Docker Engine, Compose, and Buildx. Containers run inside your sandbox VM alongside your repository and coding agents. ## Start your project's services [#start-your-projects-services] Connect from your local computer: ```sh cube connect feature/payments ``` **Sandbox:** from a repository with a Compose file: ```sh docker compose up -d docker compose ps docker compose logs -f ``` `up -d` runs the containers in the background. `logs -f` follows their output; `Ctrl+C` stops following logs and leaves the containers running. ## Preview a containerized app [#preview-a-containerized-app] Publish the container's application port to the sandbox VM. For example, a Compose service listening on port 3000 in its container can publish it with: ```yaml ports: - "127.0.0.1:3000:3000" ``` The application inside the container must listen on an interface reachable through Docker's published port, usually `0.0.0.0`. Then run **locally**: ```sh cube open 3000 --session feature/payments ``` The Adria tunnel connects to the VM's published port. Keep it running while using the preview. For databases and other TCP services, use [`cube forward`](/docs/networking). ## Run several stacks in parallel [#run-several-stacks-in-parallel] Start each branch in a separate sandbox to keep its containers, volumes, and service ports independent. Both sandboxes can publish the same remote port; use different local forwarding ports to reach them from your computer. See [Parallel engineering](/docs/parallel-engineering). ## Stop services and preserve data [#stop-services-and-preserve-data] **Sandbox:** stop the Compose project when finished: ```sh docker compose down ``` Follow your Compose configuration's volume policy for data you need to keep. Pausing the sandbox preserves its disk but stops running processes. After resume, start services again as needed. Deleting the sandbox removes its disk, including Docker data stored there; export anything you need before deletion. # Environment variables (/docs/environment-variables) Save your repository's `.env` files once. Adria writes them into new and resumed computers at the same repository paths, ready for your application's usual configuration loading. Your local shell variables are not copied automatically. ## Save your environment files [#save-your-environment-files] From your repository on your **local computer**: ```sh title="Local terminal" cube env import ``` Choose the files from the list, review the paths and key names, then confirm. The preview does not print secret values. Production-named files, examples, and templates are excluded from automatic discovery. To select a specific file, including one in a subdirectory: ```sh title="Local terminal" cube env import apps/api/.env ``` Use `cube env import --dry-run` to preview without uploading. Adria stores the values encrypted; it does not copy comments or preserve the original formatting. Files already tracked by Git are not overwritten in the sandbox. ## Share defaults with your team [#share-defaults-with-your-team] Imports are personal by default. To save repository defaults for your team: ```sh title="Local terminal" cube env import --shared apps/api/.env ``` Publishing shared defaults requires GitHub write access to the repository. Your personal values override shared values with the same key and file path. They are delivered only to your own computers. ## Update a running computer [#update-a-running-computer] Import again after changing a local file. New and resumed computers receive the saved values. For a computer that is already running: ```sh title="Local terminal" cube env apply feature/payments ``` Restart applications to load changed values. This is not continuous file sync. Adria preserves edits made to managed files inside the sandbox and reports conflicts. Use `cube env apply feature/payments --force` only when you want to replace those edits. Each import replaces the saved keys for the selected files and scope. Other files and the other scope stay unchanged. ## Inspect or remove saved configuration [#inspect-or-remove-saved-configuration] ```sh title="Local terminal" cube env list cube env remove apps/api/.env --key DATABASE_URL ``` The list shows paths and key names, not secret values. Omit `--key` to remove all personal values for that file. Add `--shared` to manage shared defaults. Removing a personal override reveals any shared default on the next refresh. ## Set a variable for one command [#set-a-variable-for-one-command] Inside the sandbox, use normal shell assignments: ```sh title="Sandbox terminal" APP_ENV=development bun run dev ``` Use `export APP_ENV=development` for the current shell. Exports disappear when that shell exits. A saved `.env` file stays on disk, but your application must load it; Adria does not export its values into every shell. ## Agent credentials [#agent-credentials] Use [`cube auth`](/docs/agents/coding-agents) for model-provider credentials. [Agent setup imports](/docs/agents/configuration) manage settings and skills separately from repository environment files. Terminal capture can record input and output. See [capture controls](/docs/logs) before entering secrets in a remote terminal. # Frequently asked questions (/docs/faq) ## Is a sandbox a container? [#is-a-sandbox-a-container] An Adria sandbox is a Linux VM with its own filesystem and processes. You can run Docker containers inside it. ## Is a Session different from a sandbox? [#is-a-session-different-from-a-sandbox] Session is the name used by the CLI for your sandbox. It associates the computer with a repository and branch. ## Can I use my own coding agent? [#can-i-use-my-own-coding-agent] Yes. The standard image includes Codex, Claude Code, and Pi. [Connect your credentials](/docs/agents/coding-agents), then launch the agent inside the sandbox. ## Does Adria include a built-in agent? [#does-adria-include-a-built-in-agent] The dashboard supports [Adria workflows](/docs/agents/workflows). The current workflow reviews merged pull requests and proposes architecture documentation updates in Notion, with approval for each page proposal. ## What survives a pause? [#what-survives-a-pause] Files on the Session disk survive. Running processes, RAM, tmux terminals, agent processes, and browser tabs do not. Restart them after resuming. ## Are local files copied when I start? [#are-local-files-copied-when-i-start] The repository is checked out from GitHub. Local uncommitted changes, unpushed commits, and ignored files are not copied automatically. Push commits first, or [transfer files explicitly](/docs/files). For `.env` files, use [`cube env import`](/docs/environment-variables) to save them once for new and resumed computers. ## Can two sandboxes use the same port? [#can-two-sandboxes-use-the-same-port] Yes. Each has an independent network environment. Use separate local ports when [forwarding both to your computer](/docs/networking). ## Does closing a terminal stop billing? [#does-closing-a-terminal-stop-billing] No. The VM keeps running until paused or deleted. Running VMs use compute credits. Inspect them with `cube sessions` and check [usage and credits](/docs/platform/usage). ## Are agent model costs included? [#are-agent-model-costs-included] No. Your subscription includes Adria compute credits. Coding-agent subscriptions and model usage are billed separately by your provider. ## Can I recover a deleted sandbox? [#can-i-recover-a-deleted-sandbox] Deleting a Session permanently removes its disk. Push commits and copy any files you need before using `cube kill`. ## Where should I start if something fails? [#where-should-i-start-if-something-fails] See [troubleshooting](/docs/faq/troubleshooting) for authentication, startup, configuration, previews, and desktop issues. # Troubleshooting (/docs/faq/troubleshooting) ## The CLI cannot reach Adria [#the-cli-cannot-reach-adria] Confirm you are using the CLI and connection instructions provided for your workspace. Early distributions need the workspace API origin configured as instructed by your Adria contact. If the error refers to `127.0.0.1` or `localhost` on your computer, the CLI is targeting a local development service. Use your workspace's connection instructions before running `cube login`. ## GitHub authorization is missing [#github-authorization-is-missing] Run `cube auth` to check status, then `cube auth github` to connect or renew authorization. Confirm your GitHub account has access to the target repository. For a missing dashboard repository, check the [GitHub App installation](/docs/platform/github) and allow time for indexing. ## A branch name is ambiguous [#a-branch-name-is-ambiguous] Run the command from the intended repository, or use the Session UUID from `cube sessions`. Adria uses your repository and Git remotes to resolve branches. See [repository selection](/docs/repositories). ## Startup is taking longer than expected [#startup-is-taking-longer-than-expected] ```sh title="Local terminal" cube start feature/payments --diagnostics --timeout 30m ``` The default readiness timeout is 20 minutes. A timeout or Ctrl+C ends the local wait; it does not necessarily delete the requested Session. Check `cube sessions` before starting another one. ## My agent configuration is not available [#my-agent-configuration-is-not-available] Run `cube config status`. A queued import is still local; an accepted import may still be preparing. Wait for `ready`. Import again after local changes. Existing Sessions pick up changed imports on subsequent agent launches. MCP tools may need their own dependencies or login. ## My environment files are missing or out of date [#my-environment-files-are-missing-or-out-of-date] From your local repository, run `cube env list` to check the saved paths and key names. Import the files if needed, then use `cube env apply ` for a running computer. Restart your app to load the values. If Adria reports a conflict, it has preserved edits made inside the sandbox. Review them before applying with `--force`. See [Environment variables](/docs/environment-variables). ## A preview will not connect [#a-preview-will-not-connect] Check that the Session is ready and the server is running on the port you are forwarding. `cube open` and `cube forward` do not resume a paused VM. If the app runs in Docker, publish its port to the VM. Use the local address printed by the forwarding command, especially when your requested port is occupied. ## Desktop commands report desktop\_not\_installed [#desktop-commands-report-desktop_not_installed] Desktop capabilities require an image with computer-use support. A CLI update alone does not add them to an existing sandbox. Use a supported image for your workspace; see [computer use](/docs/computer-use). ## Agent status says unknown [#agent-status-says-unknown] Status is based on observed agent activity and requires capture support in the image. Capture gaps, older images, or an unrecognized agent interface can leave the state unknown. Inspect the actual terminal before assuming the task has stopped. ## A Notion update conflicts [#a-notion-update-conflicts] The page changed after the proposal was created. Review its current content and the proposal before retrying. See [reviewing agent work](/docs/agents/reviewing-work). # File operations (/docs/files) Each sandbox has its own filesystem. Your repository lives at `/home/cube/workspace/`. Use normal Linux tools inside the sandbox and OpenSSH tools to copy files between the sandbox and your computer. ## Work with files in the sandbox [#work-with-files-in-the-sandbox] **Local:** open the remote repository: ```sh cube connect feature/payments ``` **Sandbox:** inspect or create files with your usual tools: ```sh pwd ls mkdir -p artifacts printf 'Hello from Adria\n' > artifacts/hello.txt cat artifacts/hello.txt ``` Other terminals in this Session see the same files. Other sandboxes have independent filesystems. ## Transfer files over SSH [#transfer-files-over-ssh] **Local:** replace `YOUR_SESSION_UUID` with the UUID from `cube sessions`, then create a temporary SSH config: ```sh session=YOUR_SESSION_UUID config=$(cube connect "$session" --ssh-config) ``` Replace `your-repository` with the sandbox's repository directory. Upload a local file into that checkout: ```sh scp -F "$config" ./input.json "cube-$session:/home/cube/workspace/your-repository/input.json" ``` Download the artifact created above: ```sh scp -F "$config" "cube-$session:/home/cube/workspace/your-repository/artifacts/hello.txt" ./hello.txt ``` For an interactive file-transfer session: ```sh sftp -F "$config" "cube-$session" ``` The access grant expires after five minutes. Generate a fresh config for later connections, and remove its private temporary directory when finished. ## Keep work across sessions [#keep-work-across-sessions] Files stay on the disk when you disconnect or pause. Deleting a sandbox removes its disk, including uncommitted work and generated artifacts. Commit and push source changes you want to keep. Download artifacts and other files before deletion. New sandboxes start from GitHub and do not automatically receive files from an earlier sandbox or your computer. See [Repositories and branches](/docs/repositories) and [Lifecycle](/docs/lifecycle). # Adria Docs (/docs) Adria gives each task its own development computer, with your code, tools, and saved environment. Run an agent, tests, and services there while you keep using your own terminal and browser. After signing in, start a branch from your local repository: ```sh title="Local terminal" cube start feature/search ``` Adria opens a shell in the remote checkout. Start another branch to work in parallel. The CLI calls each computer a **Session**. ## Start building [#start-building] Sign in once, then start a computer with one command. Bring Codex, Claude Code, or Pi to your sandbox. Give independent tasks and agents separate computers. Open a remote development server in your browser. ## Sandbox basics [#sandbox-basics] Explore the Linux environment where your code runs. Choose repositories, branches, and starting refs. Save your environment files once and reuse them. Connect, pause, resume, and delete your computer. Work from your terminal, cmux, or tmux. Transfer files between your computer and a sandbox. Open the remote browser and interact with the desktop. Understand compute credits and concurrent VM limits. ## Connect and automate [#connect-and-automate] These integrations are for dashboard workflows. They are not required to start a development computer from the CLI. Connect repositories for indexing and workflows. Give workflows access to your documentation. Propose documentation updates from merged pull requests. Resolve common setup and connection issues. ## Documentation for agents [#documentation-for-agents] Copy a guide as Markdown with **Copy page**. Agents can discover every guide through [llms.txt](/llms.txt), or read the complete documentation through [llms-full.txt](/llms-full.txt). # Lifecycle (/docs/lifecycle) Run these commands on your **local computer**. A Session can be selected by its branch name or UUID. Use the UUID from `cube sessions` outside a repository or when a branch name matches more than one Session. ## Create or resume [#create-or-resume] From a local GitHub repository: ```sh cube start feature/payments ``` Adria creates or reuses your Session for the branch, resumes it if stopped, and opens a shell when it is ready. Starting the same branch again reconnects you to that Session; use another branch for an independent sandbox. ## List and reconnect [#list-and-reconnect] ```sh cube sessions cube connect feature/payments ``` `connect` opens an existing Session and resumes it if paused. Type `exit` in the remote shell to return to your local terminal. Exiting does not pause the VM. For connection recovery and named persistent terminals, see [SSH and terminals](/docs/ssh). For running commands without opening a shell, see [Commands and processes](/docs/commands). ## Pause and resume [#pause-and-resume] ```sh cube pause feature/payments cube sessions ``` The pause request returns before shutdown finishes. Wait for `stopped` in `cube sessions`. Resume with either command: ```sh cube start feature/payments # Or: cube connect feature/payments ``` | Action | Files and Git changes | Running processes | | ------------------------------------- | ---------------------- | ------------------------------------ | | Disconnect from a persistent terminal | Kept | Continue while the VM runs | | Pause | Kept on disk | End; restart them after resume | | Resume | Existing disk restored | Start your services and agents again | | Kill | Permanently deleted | End | Pausing retains commits, staged changes, untracked files, and installed dependencies on the Session disk. It does not preserve RAM, tmux sessions, or running containers and agents. ## Check usage [#check-usage] ```sh cube usage cube usage --detailed ``` Usage shows active VM time and an estimated cost for the current UTC calendar month. `--detailed` adds a per-Session breakdown. Stopped time is excluded; leaving a shell keeps the VM running. See [Usage and credits](/docs/platform/usage) for the estimate and your plan's credit policy. ## Delete a sandbox [#delete-a-sandbox] Push commits or copy out any files you need before deleting. Then run locally: ```sh cube kill feature/payments cube sessions ``` **Deletion permanently removes the Session and its disk**, including work you have not pushed. The command returns when the request is accepted; use `cube sessions` to follow deletion progress. ## Startup help [#startup-help] If preparation is taking longer than expected, show diagnostics or allow more time. The default wait limit is 20 minutes; it is not a typical startup duration: ```sh cube start feature/payments --diagnostics --timeout 30m ``` Pressing `Ctrl+C` during preparation cancels your local wait. It does not delete the Session; inspect it with `cube sessions` and connect later. # Logs and agent status (/docs/logs) Adria separates VM lifecycle from agent activity. A ready VM can contain a working agent, a waiting agent, or no agent at all. ## Check activity [#check-activity] ```sh title="Local terminal" cube sessions cube sessions --json ``` The listing shows **VM** and **AGENT** columns. Several agents in different terminals can appear on one Session. JSON includes individual terminal observations and timestamps. | Agent state | Meaning | | ----------- | ----------------------------------------------------------------- | | `working` | Recent native agent activity or recognized terminal activity | | `waiting` | An approval or confirmation prompt was observed | | `idle` | A turn completed, was interrupted, or returned to an input prompt | | `pausing` | An interrupt was sent | | `exited` | The recorded terminal process exited | | `unknown` | There is no usable evidence of the agent's state | | `disabled` | Terminal capture is off | States are observations, not a guarantee that a task succeeded. A quiet terminal alone does not prove that an agent is idle. When the VM is not ready, the listing marks the agent state as **last observed**. ## Control terminal capture [#control-terminal-capture] On supported images, terminal capture is enabled by default. It records terminal input and output, including input entered at prompts. Avoid entering secrets into a captured terminal. ```sh title="Local terminal" cube sessions capture feature/payments off cube sessions capture feature/payments on ``` The setting applies to all terminals in the Session. Turning capture off stops further collection; it does not delete previously captured data. Turning it on mid-conversation can leave status unknown until fresh agent activity identifies it. Older images may not have capture support. Native status is supported for Codex and Claude Code on updated images, with terminal inference as a fallback. ## Read application logs [#read-application-logs] Use your application's normal logs inside the sandbox: ```sh title="Sandbox terminal" tail -f ./logs/app.log docker compose logs -f ``` A file log is not automatically a captured terminal stream. Adria does not provide a `cube logs` command; use [remote execution](/docs/commands), SSH, or your application's tools to inspect it. # Networking and tunnels (/docs/networking) Your application runs inside the sandbox. Use the Adria CLI on your **local computer** to connect its port to local loopback over SSH. ## Start a development server [#start-a-development-server] **Local:** open a persistent terminal for the server: ```sh cube connect feature/payments --tmux web ``` **Sandbox:** run your project's development command. For a Bun project with a `dev` script configured for port 3000: ```sh bun install bun run dev ``` Use the port your server actually prints. Detach with `Ctrl+B`, then `D` to keep it running while you open the preview locally. ## Open a preview [#open-a-preview] **Local:** ```sh cube open 3000 --session feature/payments ``` Adria forwards sandbox port 3000 and opens the local address in your browser. Keep the command running while using the application. `Ctrl+C` closes the tunnel; it leaves the remote server running. The tunnel reaches the sandbox's `localhost`, so a server listening on remote loopback works. If it runs in Docker, publish the container port to the VM first. ## Forward any TCP service [#forward-any-tcp-service] ```sh # Local: connect a database client to localhost:5432. cube forward 5432 --session feature/payments # Or map remote port 3000 to local port 8080. cube forward 3000:8080 --session feature/payments ``` The syntax is **remote-port:local-port**. Run each tunnel in a separate terminal. If the requested local port is occupied, Adria can select an available one; use the address printed by the command. Both `open` and `forward` bind to `127.0.0.1` on your computer. They do not create a public preview URL. Other people need their own authorized access. ## Select the right sandbox [#select-the-right-sandbox] Use `--session ` when working with several sandboxes. Without that flag, Adria uses `CUBE_SESSION_ID` if set, then your local Git branch. Port commands require a ready Session. They do not start or resume compute. If the Session is paused, run `cube connect `, restart the service, then open the tunnel from a local terminal. ## Troubleshooting [#troubleshooting] | Symptom | What to check | | ------------------------------------------ | ------------------------------------------------------------------------ | | The Session is not ready | Connect or start it first and wait for readiness. | | The browser cannot reach the app | Confirm the process is running and use its actual listening port. | | A container app is unreachable | Publish its container port on the sandbox VM. | | The local port differs from the example | Use Adria's printed address or choose another local port with `forward`. | | A preview stops after closing the terminal | Keep the forwarding command running for the lifetime of the preview. | To open Chromium **inside** a sandbox instead, see [Computer use](/docs/computer-use). # Parallel engineering (/docs/parallel-engineering) Use one sandbox per task so agents can edit, build, and test independently. For example, implement payments while another agent investigates a login bug. Each task gets its own checkout, dependencies, services, and terminal processes. ## Start two tasks [#start-two-tasks] After [installing and signing in](/docs/quickstart), open two local terminals in the same repository. [Configure the agents](/docs/agents) you want to use once before launching them. **Local terminal A:** ```sh cube start feature/payments --tmux agent ``` **Inside sandbox A:** ```sh codex ``` Give the agent a task such as: “Add validation to the payment form and test invalid amounts.” Detach with `Ctrl+B`, then `D` to leave it running. **Local terminal B:** ```sh cube start fix/login --tmux agent ``` **Inside sandbox B:** ```sh claude ``` Give this agent an independent task, such as: “Reproduce the expired-session login failure, fix it, and add a regression test.” You can use the same agent in both sandboxes instead. The tmux name `agent` is local to each VM. ## Follow progress [#follow-progress] **Local:** list the Sessions or return to an agent's terminal: ```sh cube sessions cube connect feature/payments --tmux agent ``` To inspect a checkout without attaching to the agent's terminal, open another shell or run a command: ```sh cube connect fix/login # Or, from a local terminal: cube connect fix/login --command 'git status --short' ``` Multiple terminals in one Session share files. Use separate Sessions for tasks that should change code independently. ## Preview both applications [#preview-both-applications] Start each project's development server inside its sandbox. Both can use remote port 3000. Then run these **locally**, each in its own terminal: ```sh cube forward 3000:3001 --session feature/payments ``` ```sh cube forward 3000:3002 --session fix/login ``` Open `http://127.0.0.1:3001` and `http://127.0.0.1:3002` to compare the apps. Check the printed addresses if a requested local port was already occupied. Keep both commands running while you use the previews. ## Review and finish each task [#review-and-finish-each-task] Inside each sandbox, inspect the diff and run the repository's tests. Commit and push the changes you want to keep using your normal Git workflow. Separate sandboxes isolate execution; normal Git review and conflict resolution still apply when combining their branches. **Local:** pause unfinished work or delete a finished sandbox after saving it: ```sh cube pause feature/payments cube kill fix/login ``` Pause keeps the disk but stops the agent and services. Kill permanently deletes the disk. See [Sandbox lifecycle](/docs/lifecycle) for persistence and usage. # Account and access (/docs/platform/access) Your Adria login, GitHub authorization, and model-provider credentials have different roles. Connecting one does not replace the others. ## Sign in from the CLI [#sign-in-from-the-cli] ```sh title="Local terminal" cube login ``` Complete the browser flow. For a terminal that cannot open a browser: ```sh title="Local terminal" cube login --no-browser ``` Follow the printed URL and one-time completion instructions. Use `cube auth` to inspect configured GitHub and agent credentials. ## Configure an agent [#configure-an-agent] Use `cube auth codex`, `cube auth claude`, or `cube auth pi --provider anthropic`. The prompt hides the credential; saved credentials are used for agent launches in your sandboxes. Provider billing and credential validity remain with the provider. Importing settings does not import subscription login sessions. ## Sign out or revoke a credential [#sign-out-or-revoke-a-credential] ```sh title="Local terminal" cube logout ``` This revokes and removes the local Adria CLI login. It preserves centrally configured agent credentials. Use `cube auth --remove` to disable future delivery of an agent credential. Already running agents may retain it; revoke it with the model provider to invalidate it. ## Review what agents can access [#review-what-agents-can-access] Agents run with access to the sandbox repository, installed tools, and configured services. Imported settings can contain hooks and secrets. Review imports and follow your agent's own permission controls. Terminal capture can record input and output on supported images. Review [capture controls](/docs/logs) before entering sensitive values in a terminal. # GitHub (/docs/platform/github) Adria uses GitHub for repository context, pull request events, and sandbox checkouts. Dashboard source installation and CLI authorization serve different parts of that workflow. For development computers, start with `cube login`; it guides you through GitHub authorization. Install a dashboard source when you also want repository indexing and event-driven workflows. ## Connect a dashboard source [#connect-a-dashboard-source] 1. Open **Settings** in the Adria dashboard. 2. In **GitHub App**, select **Install App**. 3. Choose the GitHub account and repositories to give Adria access to. 4. Complete installation and return to Adria. Adria starts indexing the selected repositories and receiving their events. Use **Update Install** to change the installation's repository selection. The integration reads repository contents, metadata, pull requests, and issues. GitHub installation permissions and the selected repositories determine its scope. ## Authorize the CLI [#authorize-the-cli] ```sh title="Local terminal" cube login ``` Complete the browser flow and wait for confirmation that GitHub is connected. To connect or renew GitHub authorization separately: ```sh title="Local terminal" cube auth github ``` ## Select a repository [#select-a-repository] Run sandbox commands from a local GitHub checkout. Adria identifies the repository from Git remotes and prepares a separate remote checkout. See [repositories and branches](/docs/repositories) for ambiguous remotes, branch selection, and working with local commits. ## Use repository events [#use-repository-events] Once your dashboard source is indexed, select its repositories when [creating an Adria workflow](/docs/agents/workflows). The current workflow trigger uses pull requests merged into `main` in the selected repositories. # Adria platform (/docs/platform) The Adria dashboard brings your repositories, documentation, and workflows together. The CLI connects your terminal to sandbox computers. ## Connect your sources [#connect-your-sources] Connect repositories and receive events for Adria workflows. Index documentation and apply approved page updates. Understand CLI sign-in and separate agent credentials. Understand compute credits, track running time, and stop idle compute. ## Choose how to work [#choose-how-to-work] For interactive development, [start a sandbox](/docs/quickstart) and launch your coding agent. For event-driven documentation work, [create an Adria workflow](/docs/agents/workflows). Connecting a repository for dashboard indexing and signing the CLI into GitHub are separate steps. Use the instructions for the workflow you are setting up. # Notion (/docs/platform/notion) Connect a Notion integration so Adria can index your documentation and apply approved workflow proposals. ## Prepare your integration [#prepare-your-integration] Create a Notion integration with the capabilities needed to read documentation and write the page updates you want Adria to apply. Share the relevant pages with that integration in Notion. A token alone does not grant access to pages that have not been shared. ## Connect it to Adria [#connect-it-to-adria] Open **Settings** in the dashboard and find the **Notion** section. Enter a source name and your integration token, then save the source. The dashboard can start an initial sync when creating it. Use the source's sync control to refresh its indexed content. Wait for the relevant pages to appear before using them in a workflow. ## Choose the workflow scope [#choose-the-workflow-scope] When [creating a workflow](/docs/agents/workflows), select the Notion source and architecture root page. Adria uses the connected documentation as context and proposes relevant architecture updates. ## Review before application [#review-before-application] Workflow page changes require approval. Inspect the proposed page content and evidence in the dashboard before approving a create or update action. Existing-page updates use the revision they were prepared against. If the page has changed, [review the conflict](/docs/agents/reviewing-work) before retrying the proposal. ## Resolve missing pages [#resolve-missing-pages] Check that the integration has access to the page and its intended parent, then sync again. If a page is still missing, confirm its permissions and the selected source before changing the workflow scope. # Usage and credits (/docs/platform/usage) Your monthly subscription includes the same dollar amount of compute credits. Credits pay for running computers; concurrency is how many VMs you can run at once. More terminals on the same computer do not use another VM. ## Plans and compute credits [#plans-and-compute-credits] | Plan | Monthly price and included credits | Concurrent VMs | | ---------- | ---------------------------------- | -------------- | | Individual | $20 | 10 | | Team | $199 | 100 | | Scale | $499 | 300 | | Enterprise | Custom | Custom | A standard VM has 4 vCPU and 8 GB RAM and costs $0.25/hour. For example, $20 in credits covers about 80 standard VM-hours: one VM for 80 hours, or two for 40 hours each. Other configurations use credits at their own hourly rates. Unused monthly credits expire. Purchased credits roll over. Add credits when you need more compute, or upgrade when you need more concurrent VMs. Coding-agent subscriptions and model-provider usage are separate. ## Check running time [#check-running-time] ```sh title="Local terminal" cube usage cube usage --detailed ``` The CLI shows VM runtime for the current UTC calendar month; `--detailed` adds a breakdown by Session. Its current cost estimate uses the standard $0.25/hour rate. It is not a credit balance or a final bill for different VM sizes. ## Stop idle compute [#stop-idle-compute] Leaving a terminal does not pause the VM. Run locally when you are done: ```sh title="Local terminal" cube pause feature/payments cube sessions ``` The pause command confirms the request before shutdown finishes. Check the listing for `stopped`. Pause keeps your files but stops agents and services. Resume with `cube connect feature/payments`, then restart those processes. Use `cube kill ` only when you no longer need the computer or its disk. Push your code and copy out any files first: deletion is permanent. See [lifecycle](/docs/lifecycle). # Quickstart (/docs/quickstart) Sign in once, then start a development computer for your branch with one command. You need an Adria account and a local clone of a GitHub repository you can access. Run the setup commands on your own computer. ## Install the CLI [#install-the-cli] Use the CLI and connection instructions supplied for your Adria workspace. The Homebrew command will be: ```sh title="Local terminal" brew install CUBE_FORMULA ``` `CUBE_FORMULA` is a placeholder, not a published formula. Use your workspace's installation instructions until it is replaced. Check the installation with `cube --version`. ## Sign in once [#sign-in-once] ```sh title="Local terminal" cube login ``` Complete sign-in and GitHub authorization in the browser. Wait for the terminal to confirm that you are signed in and GitHub is connected. ## Start your computer [#start-your-computer] From your local repository: ```sh title="Local terminal" cd ~/src/your-repository cube start feature/hello-adria ``` Adria prepares a VM, checks out the branch, and opens a shell in the repository. If the branch does not exist on GitHub, it starts from the default branch. Start another branch to get another independent computer. Your checkout comes from GitHub. Push any local commits you want to use first; uncommitted changes are not copied. If your app needs `.env` files, [save them once](/docs/environment-variables) before starting. ## Run your coding agent [#run-your-coding-agent] Codex, Claude Code, and Pi are already installed. To use one, connect its credential once from **another local terminal**. Choose the agent you use: ```sh title="Local terminal" cube auth codex ``` Paste your OpenAI API key at the hidden prompt. ```sh title="Local terminal" cube auth claude ``` Paste your Anthropic API key. A [setup token](/docs/agents/claude-code) is also supported. ```sh title="Local terminal" cube auth pi --provider anthropic ``` Paste the API key for your chosen provider. Back in the remote shell, launch your agent and give it a task: ```sh title="Sandbox terminal" codex # Or: claude # Or: pi ``` The agent, tests, and development server run on the same computer. Agent and model costs are separate from Adria compute. You can also [bring your settings and skills](/docs/agents/configuration). ## Leave and return [#leave-and-return] To keep an agent running while you disconnect, use a [named terminal](/docs/terminals). Leaving a shell does not pause the VM. When you want to stop compute, quit the agent and type `exit` to leave the remote shell. Then run locally: ```sh title="Local terminal" cube pause feature/hello-adria ``` Pause keeps your files and stops processes. Return later with: ```sh title="Local terminal" cube connect feature/hello-adria ``` Restart your agent and services after a pause. ## Next steps [#next-steps] Give each task and agent its own computer. Open a remote development server in your local browser. # Remote development (/docs/remote-development) Keep your terminal and browser on your computer while the repository, tools, and services run together in a sandbox. This walkthrough uses a Bun web project with a development server on port 3000; use your project's commands and port. ## Start your development computer [#start-your-development-computer] After [installing the CLI and signing in](/docs/quickstart), run **locally** from your repository: ```sh cube start feature/web-app ``` **Sandbox:** install dependencies and inspect the checkout: ```sh bun install git status ``` Work in this shell, or [launch a coding agent](/docs/agents). Type `exit` to return to your local terminal when you are ready to open another remote terminal. ## Run the application [#run-the-application] **Local:** ```sh cube connect feature/web-app --tmux web ``` **Sandbox:** ```sh bun run dev ``` Detach with `Ctrl+B`, then `D`. The server keeps running while the sandbox runs. ## Preview and test [#preview-and-test] **Local:** open the application in your browser: ```sh cube open 3000 --session feature/web-app ``` Keep the tunnel running. In another local terminal, run the project's tests: ```sh cube connect feature/web-app --command 'bun test' ``` Use the [remote browser](/docs/computer-use) when the browser itself needs to run inside the sandbox, or [Docker](/docs/docker) for containerized dependencies. ## Return to the work later [#return-to-the-work-later] Review and push changes inside the sandbox using your normal Git workflow. When you stop for the day, run **locally**: ```sh cube pause feature/web-app ``` The disk keeps your checkout and dependencies. Later, reconnect: ```sh cube connect feature/web-app ``` Restart the server and other processes, then reopen the preview tunnel. See [Lifecycle](/docs/lifecycle) for usage and permanent deletion. # Repositories and branches (/docs/repositories) Adria creates sandboxes from GitHub repositories. Run the CLI from a local checkout; Adria identifies the repository and prepares a separate checkout on the remote computer. ## Identify your repository [#identify-your-repository] **Local**, from the repository or one of its subdirectories: ```sh cube init ``` Adria uses the current branch's upstream remote, then `origin`, then a sole remote. Linked worktrees are supported. If several remotes are ambiguous, configure the branch's upstream before starting. Use `cube init --json` to inspect the detected repository, branch, HEAD, and local Git state in a script. Identification does not upload your local files. ## Choose a branch [#choose-a-branch] ```sh cube start feature/payments ``` If that branch exists on GitHub, Adria checks it out. Otherwise it creates the branch from the repository's default branch. The shell opens in `/home/cube/workspace/`. Starting a branch that already has a Session reuses that Session. Its current checkout and work remain in place. Choose another branch for an independent sandbox. ## Start from another remote ref [#start-from-another-remote-ref] To create a new branch from an existing remote ref: ```sh cube start feature/payments-v2 --source-ref origin/release ``` Replace `origin/release` with a remote ref in your repository. `--source-ref` chooses the starting point for a new branch; it does not reset an existing Session. ## Move work between computers [#move-work-between-computers] The sandbox starts from GitHub, not from your local working tree. Push commits you want to use before starting. Uncommitted changes, ignored files, and local commits that have not been pushed are not copied automatically. Save repository `.env` files with [`cube env import`](/docs/environment-variables) to reuse them in new and resumed computers. Agent settings and skills have their own [configuration import](/docs/agents/configuration). Inside the sandbox, use Git normally to review, commit, and push changes. Use [file operations](/docs/files) for individual files you need to transfer. Separate sandboxes do not synchronize their working trees; combining their changes still uses your normal Git review and merge workflow. ## Repository access [#repository-access] Sign-in connects your GitHub account. Adria checks account and repository access before preparing the Session. If GitHub authorization expires, run **locally**: ```sh cube auth github ``` Use a Session UUID from `cube sessions` when connecting outside a repository or when a branch name matches multiple Sessions. # Runtime and tools (/docs/sandboxes) An Adria sandbox is a Linux VM with its own filesystem and processes. The standard Session image provides a development environment for your repository, agents, and services. The shell opens in `/home/cube/workspace/` as the `cube` user. ## Included tools [#included-tools] | Category | Tools | | ------------------------- | ------------------------------------- | | Source control | Git and GitHub CLI | | Containers | Docker Engine, Compose, and Buildx | | JavaScript and TypeScript | Node.js, npm, pnpm, and Bun | | Other runtimes | Python, uv, Go, Java, and Rust | | Coding agents | Codex, Claude Code, and Pi | | Browser automation | Playwright and Chromium | | Terminal | OpenSSH, tmux, and common shell tools | Agent packages are installed without customer credentials. [Connect your agents](/docs/agents) before launching them. Interactive desktop capabilities require an image with [computer-use support](/docs/computer-use). ## Install project dependencies [#install-project-dependencies] Use your repository's usual setup commands **inside the sandbox**. For a Bun project, for example: ```sh bun install bun run build ``` Installed dependencies and files stay on the Session disk across disconnects and pauses. [Save your environment files](/docs/environment-variables) once to reuse them in new and resumed computers. Other local files and shell variables are not automatically copied. ## Run services [#run-services] The `cube` user can run Docker and use `sudo` inside the VM. Start databases and other dependencies using your project's setup, or follow [Run Docker](/docs/docker). Agents with this access can modify the sandbox's files and services. Separate sandboxes can use different dependency versions and the same service ports. Terminals connected to one Session share its filesystem and processes. Use [local tunnels](/docs/networking) to reach a service from your computer. ## Keep your setup [#keep-your-setup] Adria prepares the repository and your saved setup before opening the shell. Updating your local CLI does not replace an existing Session's image or disk. A paused Session resumes with its existing files; you must restart its services and agents. Deleting the Session permanently removes those files. See [Lifecycle](/docs/lifecycle). # SSH and terminals (/docs/ssh) Adria opens an SSH shell after the Session is ready. Your terminal runs locally; commands in that shell run in the remote repository. ## Connect to a sandbox [#connect-to-a-sandbox] **Local:** ```sh cube connect feature/payments ``` Use the Session UUID from `cube sessions` outside a repository or when branch names are ambiguous. `connect` resumes a paused Session before opening its shell. Type `exit` in the remote shell to return to your local computer. Leaving the shell does not pause the VM. ## Use several terminals [#use-several-terminals] Run `cube connect` in another local terminal to open a separate shell in the same sandbox. Both shells share files and services. For tasks that should edit code independently, use [separate sandboxes](/docs/parallel-engineering). Adria detects supported terminal integrations automatically. To stay in the current terminal explicitly: ```sh cube connect feature/payments --terminal current ``` ## Disconnect and reconnect [#disconnect-and-reconnect] Ordinary interactive shells can recover from a temporary SSH interruption while the VM keeps running. Keep the local pane open for automatic recovery. Closing the pane does not automatically reattach that terminal on a later launch. For a terminal you can deliberately detach and return to by name: ```sh cube connect feature/payments --tmux work ``` Detach with `Ctrl+B`, then `D`, and run the same command to reattach. Two panes using the same tmux name share that terminal. Distinct names give separate terminals. A pause stops these processes even though the disk is preserved. ## Use standard OpenSSH tools [#use-standard-openssh-tools] Adria can export a temporary SSH configuration. **Local:** replace `YOUR_SESSION_UUID` with the UUID from `cube sessions`: ```sh session=YOUR_SESSION_UUID config=$(cube connect "$session" --ssh-config) ssh -F "$config" "cube-$session" ``` The CLI prints only the config path to stdout. That file uses a `cube-` host alias and references the private key and trusted host key. The access grant expires after five minutes; generate another config for new connections after that. The files share a private temporary directory you can remove when done. Use this configuration with `scp` and `sftp` for [file transfers](/docs/files). For a single command, `cube connect --command` handles temporary access for you; see [Commands and processes](/docs/commands). # Terminal integrations (/docs/terminals) Adria connects your local terminal to the sandbox over SSH. Multiple terminals on the same Session share the checkout, files, and running services. ## Choose a local terminal [#choose-a-local-terminal] ```sh title="Local terminal" cube connect feature/payments --terminal current cube connect feature/payments --terminal cmux cube connect feature/payments --terminal tmux ``` The default is `auto`. Adria uses the available terminal integration, or the current terminal. Select `current` when you want the shell in the pane you are already using. In cmux, the workspace is bound to the Session so additional splits can connect to the same computer. Use separate workspaces for separate sandboxes. ## Keep a remote terminal running [#keep-a-remote-terminal-running] A local tmux integration and a remote tmux session have different roles. `--terminal tmux` selects the local integration; `--tmux` names a terminal running inside the sandbox: ```sh title="Local terminal" cube connect feature/payments --tmux agent ``` Run an agent or server in that terminal. Detach with **Ctrl+B**, then **D**, and reattach with the same command. The remote terminal keeps running while the VM runs. ## Disconnect and reconnect [#disconnect-and-reconnect] Interactive connections can reconnect after a temporary network interruption. A disconnected terminal does not pause the sandbox or stop compute usage. Pause stops all processes, including tmux and agents. After resuming, your files remain, but you must restart those processes. See [lifecycle](/docs/lifecycle). ## Connect an editor [#connect-an-editor] For editors that support OpenSSH configuration, generate a temporary config with `cube connect --ssh-config`. Follow the [SSH guide](/docs/ssh) for its short-lived credentials and standard SSH access.