Skip to main content

​
Why Use an Isolated Environment?

Sandboxed Execution

Agents run in a container with their own Node.js, Python, and tools - no conflicts with your host system.

Use Local Credentials

Mount your existing OAuth tokens and API keys - no need to reconfigure authentication.

Reproducible

Same container runs identically across machines. Share your setup with teammates.

Session Persistence

Keep your session history and logs across container restarts.

​
Quick Start

Start a persistent container that runs in the background: 
docker run -d --name agentuse-dev \
  -p 12233:12233 \
  -v ~/.local/share/agentuse:/root/.local/share/agentuse \
  -v $(pwd):/workspace \
  -w /workspace \
  ghcr.io/agentuse/agentuse:latest
This starts agentuse serve with your local credentials and workspace mounted.

​
Run Agents

curl http://localhost:12233/run \
  -H "Content-Type: application/json" \
  -d '{"agent": "/workspace/my-agent.agentuse"}'

​
Manage Container

# Stop
docker stop agentuse-dev

# Start again
docker start agentuse-dev

# Remove
docker rm -f agentuse-dev

​
What’s Included

ComponentVersionPurpose
AgentUseLatestBun-compiled binary
Node.js20.xRun JavaScript scripts
Python3.12Run Python scripts
gitLatestVersion control operations
curlLatestHTTP requests
jqLatestJSON processing
bashLatestShell scripts

​
Using Your Local Credentials

AgentUse stores credentials in ~/.local/share/agentuse/. Mount this directory to use your existing authentication: 
-v ~/.local/share/agentuse:/root/.local/share/agentuse
This gives the container access to:
  • OAuth tokens - From agentuse auth login
  • API keys - Stored via auth commands
  • Session logs - Execution history
OAuth tokens may expire. If you encounter auth errors, run agentuse auth login on your host to refresh tokens.

​
Shell Alias

Add to your ~/.bashrc or ~/.zshrc: 
# Run commands in the container
alias agentuse-docker='docker exec -it agentuse-dev agentuse'
Now use it like the native command: 
agentuse-docker run my-agent.agentuse
agentuse-docker sessions list
agentuse-docker sessions view <session-id>
Make sure the container is running first with docker start agentuse-dev.

​
Docker Compose

For easier management, use Docker Compose: 
# docker-compose.yml
version: '3.8'
services:
  agentuse:
    image: ghcr.io/agentuse/agentuse:latest
    container_name: agentuse-dev
    ports:
      - "12233:12233"
    volumes:
      - ~/.local/share/agentuse:/root/.local/share/agentuse
      - .:/workspace
    working_dir: /workspace
    restart: unless-stopped

# Start
docker-compose up -d

# Run agents
docker-compose exec agentuse agentuse run my-agent.agentuse

# Stop
docker-compose down

​
Using Environment Variables Instead

If you prefer not to mount credentials: 
docker run -d --name agentuse-dev \
  -p 12233:12233 \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -v $(pwd):/workspace \
  -w /workspace \
  ghcr.io/agentuse/agentuse:latest
Session logs won’t persist unless you mount the data directory.

​
Adding Custom Tools

If your agents need additional packages, create a custom image: 
FROM ghcr.io/agentuse/agentuse:latest

# Add what your agents need
RUN apk add --no-cache ffmpeg
RUN pip3 install --no-cache-dir pandas requests
RUN npm install -g typescript
Build and use: 
docker build -t my-agentuse .

docker run -d --name agentuse-dev \
  -p 12233:12233 \
  -v ~/.local/share/agentuse:/root/.local/share/agentuse \
  -v $(pwd):/workspace \
  -w /workspace \
  my-agentuse

​
Comparison: Isolated vs Self-Hosting

FeatureIsolated EnvironmentSelf-Hosting
PurposeLocal developmentProduction deployment
CredentialsMount from hostEnvironment variables
SessionsPersist to hostOptional persistence
WorkspaceMount local directoryBake into image or mount
Typical useSingle developerTeam/CI/CD

Self-Hosting Guide

Need to deploy for production? See the self-hosting guide.