Remote Agent

An OpenCode plugin that runs OpenCode agent tasks on ephemeral AWS ECS Fargate containers. Offload long-running coding tasks -- refactors, migrations, test suites, full feature builds -- to the cloud while you keep working locally.

Works on macOS and Linux.

How it works

Local (OpenCode)                          AWS Cloud
+-----------------+                       +------------------+
| 1. Package      |  --- S3 upload --->   | 3. ECS Fargate   |
|    workspace    |                       |    container     |
| 2. Upload       |                       |    runs OpenCode |
|    prompt +     |                       |    CLI (headless)|
|    session      |                       |                  |
|    context      |  <-- S3 download ---  | 4. Git patch     |
| 5. Apply patch  |                       |    uploaded      |
+-----------------+                       +------------------+

1. Your local workspace is packaged (respecting .gitignore) and uploaded to S3
2. Current session context is extracted so the remote agent knows what you've discussed
3. An ECS Fargate container starts with OpenCode CLI and your codebase
4. When done, a git diff patch of all file changes is uploaded to S3
5. You download the patch and apply it locally with git apply

Quickstart

Prerequisites

• OpenCode installed
• AWS CLI configured (aws configure)
• Docker installed and running
• Node.js 22+
• An API key or OAuth login for your AI provider (Anthropic, OpenAI, etc.)

1. Install the plugin

# In your OpenCode config directory
cd ~/.config/opencode
npm install opencode-remote-agent

Add to your opencode.json:

{
  "plugin": ["opencode-remote-agent"]
}

2. Deploy AWS infrastructure

From inside OpenCode, use the slash command:

/remote-setup

Or do it manually:

# Clone and build
git clone https://github.com/petrjirous/opencode-remote-agent.git
cd opencode-remote-agent
npm install
npm run build

# Bootstrap CDK (one-time, replace ACCOUNT and REGION)
npx cdk bootstrap aws://ACCOUNT_ID/REGION

# Deploy
npm run cdk:deploy

The CDK stack creates: VPC, ECS Fargate cluster, ECR repository, S3 bucket, CloudWatch log group, and IAM roles.

3. Build and push the Docker image

# Authenticate Docker with ECR
aws ecr get-login-password --region REGION | \
  docker login --username AWS --password-stdin ACCOUNT_ID.dkr.ecr.REGION.amazonaws.com

# Build and push
docker build --platform linux/amd64 -t ACCOUNT_ID.dkr.ecr.REGION.amazonaws.com/remote-agent:latest .
docker push ACCOUNT_ID.dkr.ecr.REGION.amazonaws.com/remote-agent:latest

4. Configure (mostly automatic)

The plugin auto-discovers your infrastructure from the CloudFormation stack. You only need to set the region (if not us-east-1):

export REMOTE_AGENT_AWS_REGION="us-east-1"    # Your AWS region
export REMOTE_AGENT_AWS_PROFILE="default"      # AWS CLI profile (optional)

That's it. The plugin queries the RemoteAgentStack CloudFormation stack to find the S3 bucket, ECS cluster, subnets, security group, and ECR image automatically.

You can override any value with env vars if needed (see Configuration below).

5. Use it

In OpenCode, ask the agent to run something remotely:

Use remote_run to refactor the auth module to use JWT tokens

Or use slash commands:

/remote-run Refactor the auth module to use JWT tokens
/remote-list
/remote-status TASK_ID
/remote-cancel TASK_ID

Tools

Tool	Description
remote_run	Launch a task on a remote Fargate container
remote_status	Check task status, view output, apply patch
remote_list	List all remote tasks
remote_cancel	Cancel a running task
remote_setup	Deploy/update/destroy AWS infrastructure

Slash commands

Command	Description
/remote-run <prompt>	Quick-launch a remote task
/remote-status <id>	Check task status
/remote-list	List all tasks
/remote-cancel <id>	Cancel a running task
/remote-setup	Deploy infrastructure

Configuration

After deploying with CDK, the plugin auto-discovers infrastructure from the CloudFormation stack outputs. No manual configuration is needed beyond region and profile.

Environment variable overrides (all optional if CDK stack is deployed):

Variable	Default	Description
REMOTE_AGENT_AWS_REGION	us-east-1	AWS region
REMOTE_AGENT_AWS_PROFILE	default	AWS CLI profile name
REMOTE_AGENT_S3_BUCKET	(auto)	S3 bucket for results
REMOTE_AGENT_ECS_CLUSTER	(auto)	ECS cluster name
REMOTE_AGENT_CONTAINER_IMAGE	(auto)	ECR image URI
REMOTE_AGENT_SUBNET_IDS	(auto)	Comma-separated subnet IDs
REMOTE_AGENT_SECURITY_GROUP_ID	(auto)	Security group ID
REMOTE_AGENT_PROVIDER	anthropic	AI provider from OpenCode auth
REMOTE_AGENT_MODEL	anthropic/claude-sonnet-4-5	Model in provider/model format

Authentication

The plugin forwards your AI provider credentials to the remote container. It looks for credentials in this order:

1. ANTHROPIC_API_KEY environment variable
2. OPENAI_API_KEY environment variable
3. REMOTE_AGENT_AUTH_TOKEN environment variable (explicit override for any provider)
4. OpenCode auth file at ~/.local/share/opencode/auth.json (automatic if you've run opencode auth login)

Set REMOTE_AGENT_PROVIDER to choose which provider to read from the auth file (default: anthropic).

Supported providers

Provider	Env var (direct key)	Auth file key
Anthropic	ANTHROPIC_API_KEY	anthropic
OpenAI	OPENAI_API_KEY	openai
GitHub Copilot	GITHUB_TOKEN	github-copilot
Groq	GROQ_API_KEY	groq
Google Gemini	GEMINI_API_KEY	gemini

How the remote container works

• Runs opencode run with your prompt in headless mode
• OpenCode executes in full agentic mode (reads, writes, and edits files)
• All file changes are tracked via git and captured as a unified diff patch
• The patch, output, and metadata are uploaded to S3
• You can apply the patch locally with git apply

Resource configuration

The remote_run tool accepts optional parameters:

• cpu: 256 (0.25 vCPU) to 4096 (4 vCPU). Default: 1024
• memory: 512 MB to 30720 MB. Default: 4096
• timeout_minutes: 1 to 720 (12 hours). Default: 120 (2 hours)
• include_workspace: Upload local files to container. Default: true
• include_session_context: Include conversation history. Default: true
• repo_url: Clone a git repo instead of uploading workspace

Cost estimate

• ECS Fargate (1 vCPU, 4 GB): ~$0.04/hour
• S3: negligible for typical workspace sizes
• CloudWatch Logs: negligible
• No NAT Gateway -- the VPC uses public subnets only to avoid the ~$32/month NAT cost

A typical 10-minute task costs less than $0.01 in AWS charges (plus AI provider API usage).

Cleanup

To remove all AWS resources:

cd opencode-remote-agent
npm run cdk:destroy

Or from OpenCode: /remote-setup destroy

License

MIT