Compute Providers

Run agents on local tmux, Docker containers, or EC2 instances.

Overview

Ark supports three compute providers. Each provider handles how agent sessions are launched, monitored, and cleaned up. The local provider is always available; Docker and EC2 require additional setup.

Providers declare their own isolation modes:

Local: worktree (git worktree per session) or inplace (use repo directly)
EC2: inplace (remote workspace)
Docker: container (isolated container per session)

Local Provider

The default. Agents run in local tmux sessions. No setup required beyond having tmux installed.

Auto-created on first boot. Sessions launch as ark-s-<id> tmux sessions.

ark compute list
# Shows: local  local  running

Isolation

Worktree (default): creates a git worktree at ~/.ark/worktrees/<session-id>/ so the agent works on an isolated copy
Inplace: agent works directly in the repo directory (faster, but no isolation)

Docker Provider

Run agents in Docker containers. Each session gets its own container.

Setup

ark compute create my-docker --provider docker --image ubuntu:22.04
ark compute provision my-docker

Options:

--image: Docker image (default: ubuntu:22.04)
--devcontainer: use the repo's devcontainer.json
--volume: extra volume mounts (repeatable)

How it works

Container is created from the specified image
Your repo is mounted into the container
Bun and Claude Code are installed inside the container
Agent launches in a tmux session inside the container

Provider Capabilities

Each provider declares its own capabilities, which determine what operations are available:

Capability	Local	EC2	Docker
Always running	Yes	No (needs provisioning)	No (needs provisioning)
`supportsWorktree`	Yes (git worktree per session)	No (remote clone)	No
`canReboot`	No	Yes	Yes
`canDelete`	No	Yes	Yes
Test support	No	Yes	Yes

EC2 Provider

Run agents on AWS EC2 instances. Good for heavy workloads or when you need isolation from your dev machine.

Authentication Setup

Before your first remote dispatch, set up credentials:

Run ark auth to configure Claude credentials for remote agents
Configure AWS credentials via ~/.aws/credentials or pass --profile when creating the compute
SSH keys are auto-generated per compute at ~/.ssh/ark-<name> -- no manual key management needed

On provision and dispatch, ark automatically syncs all required credentials to the EC2 instance: SSH keys, AWS credentials, git config, gh auth tokens, and Claude API keys.

Setup

ark compute create dev-box --provider ec2 --size m --arch x64 --region us-east-1
ark compute provision dev-box

EC2 instances incur AWS charges while running. Use --idle-minutes to enable auto-shutdown, and always run ark compute stop when work is done.

Instance Sizes

Size	vCPU	RAM	Label
`xs`	2	8 GB	Extra Small
`s`	4	16 GB	Small
`m`	8	32 GB	Medium
`l`	16	64 GB	Large
`xl`	32	128 GB	Extra Large
`xxl`	48	192 GB	2X Large
`xxxl`	64	256 GB	3X Large

Configuration

ark compute update dev-box --ingress "1.2.3.4/32" --idle-minutes 30

Options:

--size: instance size
--arch: x64 or arm
--region: AWS region
--profile: AWS CLI profile
--subnet-id: VPC subnet
--ingress: SSH CIDR (or "open" for 0.0.0.0/0)
--idle-minutes: auto-shutdown after idle

Post-Provision Verification

After cloud-init completes, ark automatically verifies that all required tools are installed on the instance: claude, ark, bun, tmux, and git. If any tool is missing, ark attempts auto-remediation to install it. Credentials are synced as part of this process.

SSH Connection Pool

EC2 operations use SSH ControlMaster multiplexing to avoid opening a new TCP connection for every command. Requests are managed through per-type queues:

Metrics: drops stale requests (only the latest poll matters)
Commands: FIFO queue
Sync: FIFO queue

This prevents overwhelming the remote sshd with concurrent connections.

Operations

ark compute start dev-box     # start a stopped instance
ark compute stop dev-box      # stop (preserves data)
ark compute destroy dev-box   # terminate instance
ark compute ssh dev-box       # SSH into the instance
ark compute sync dev-box      # sync environment (push/pull)
ark compute metrics dev-box   # show CPU, memory, disk, network

Monitoring

The TUI Compute tab (press 6) shows real-time metrics for running computes:

CPU, memory, disk usage
Network I/O
Running sessions
Active processes

Metrics are polled every ~9 seconds.

Dispatching to Remote Compute

When creating a session, specify the compute target:

ark session start --repo . --summary "Deploy" --compute dev-box

Or select it in the TUI's New Session form.

The agent will be launched on the remote compute. Attach via a in the TUI to get a remote tmux session. Press Ctrl+B d to detach from the tmux session without interrupting the agent.

Devcontainer and Compose

Devcontainer and Docker Compose support require explicit opt-in via arc.json in your project root:

{
  "devcontainer": true,   // use repo's devcontainer.json
  "compose": true          // use repo's docker-compose.yml
}

arc.json supports JSONC (comments are allowed in devcontainer.json as well). These options are not enabled by default to avoid unexpected container builds.