runplex

Deploy Claude Code agents to production — from simple chatbots to multi-agent systems with sub-agents, custom tools, and MCP integrations. Each user gets their own isolated sandbox. Accessible via web chat, Slack, or API.

npx runplex init      # scaffold your project
npx runplex dev       # run locally → chat at localhost:4000/chat
npx runplex deploy    # deploy to Runplex Cloud

See starter-agents for production-ready templates.

Quick Start

# 1. Scaffold your project
npx runplex init

# 2. Add your API key
cp .env.example .env
# edit .env — add ANTHROPIC_API_KEY

# 3. Run locally (requires Docker)
npx runplex dev

Open http://localhost:4000/chat — you're chatting with your agent.

Ready to ship? Deploy to Runplex Cloud:

npx runplex login
npx runplex deploy

Your agent is live at https://<project>.cloud.runplex.dev/chat.

Commands

runplex init

Scaffolds runplex.yaml + .env.example + .runplexignore. Detects your project:

• package.json → adds npm install to setup hooks
• .env.example → adds env vars to sandbox config
• Python files → suggests requirements.txt

runplex init          # interactive
runplex init --yes    # accept defaults

runplex dev

Local development server with Docker sandboxes.

runplex dev                     # port 4000 (auto-finds available)
runplex dev --port 8080         # custom port
runplex dev --provider e2b     # use real E2B sandboxes

Requires Docker. Loads .env automatically. No cloud account needed.

runplex deploy

Deploy to Runplex Cloud. No Docker, no infrastructure setup.

runplex deploy                  # deploy current project
runplex deploy --app-name mybot # custom project slug

What happens:

1. Reads runplex.yaml + resolves env vars from .env
2. Builds E2B template server-side (no E2B key needed)
3. Deploys container with managed Redis, Sylo, SSL
4. Prints URL

Hosted Chat UI

Every container serves a web chat interface at /chat — no setup required. Features:

• Streaming responses with markdown rendering
• File attachments — upload files to the agent, receive files back as image previews or download cards
• Thread list with rename, archive, delete
• Tool call display with args and results
• Thinking/reasoning blocks (collapsible)
• Dark mode toggle
• Resizable sidebar
• Mobile responsive
• Customizable via runplex.yaml (title, welcome, avatar, logo, theme)

Access at http://localhost:4000/chat (dev) or https://slug.cloud.runplex.dev/chat (deployed).

To disable: add chat: { enabled: false } to runplex.yaml.

runplex logs

Stream container logs from Runplex Cloud.

runplex logs                    # current project
runplex logs --tail 50          # last 50 lines

runplex login

Authenticate with Runplex Cloud. Get your token at https://cloud.runplex.dev/deploy-tokens.

runplex validate

Validate runplex.yaml and show config summary.

runplex setup slack

Guided Slack agent creation for self-hosted deployments. If the project is deployed to Runplex Cloud, redirects to the dashboard for managed Slack (zero config).

runplex build (self-hosted)

Build local Docker image + E2B template for self-hosted deployments. For users who deploy on their own infrastructure instead of Runplex Cloud.

runplex build                   # Docker image + E2B template
runplex build --skip-template   # Docker image only

Requires E2B_API_KEY in .env for template builds.

runplex chat (terminal)

Terminal SSE client — alternative to the web UI at /chat. Useful for headless testing or scripting.

runplex chat                                        # auto-detects URL
runplex chat --url http://localhost:4000             # local

Configuration

runplex.yaml

agent:
  sdk: claude                      # only claude supported currently
  model: claude-sonnet-4-6         # optional, has default

env:
  RUNPLEX_ADMIN_TOKEN: ${RUNPLEX_ADMIN_TOKEN}

sandbox:
  scope: conversation              # user | conversation | channel | shared
  idle_timeout: 30m
  on_idle: pause                   # pause | kill
  cpu: 2                           # E2B CPU count (default: 1)
  memory: 2048                     # E2B memory MB (default: 1024)
  env:
    ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
    GEMINI_API_KEY: ${GEMINI_API_KEY}

hooks:
  setup: ["npm install"]           # run at template build time

# Storage (optional — Cloud auto-detects from env, self-hosted set explicitly)
storage:
  endpoint: ${STORAGE_ENDPOINT}    # MinIO, R2, etc.
  bucket: ${STORAGE_BUCKET}
  accessKeyId: ${STORAGE_ACCESS_KEY}
  secretAccessKey: ${STORAGE_SECRET_KEY}

# File sync mounts (requires storage)
mounts:
  - name: knowledge
    localPath: knowledge/
    storagePath: knowledge
    scope: tenant                  # tenant (shared) or user (per-user)
  - name: user-files
    localPath: user/
    storagePath: files
    scope: user
    persist: always                # always | full | never

# Memory persistence (requires storage)
memory:
  - name: agent-memory
    localPath: memory.md
    storagePath: memory
    scope: user
    compactionThreshold: 20        # merge entries after this many

frontends:
  api: true                        # HTTP/SSE chat API
  slack: true                      # managed Slack (Cloud) or self-managed

admin: true                        # admin panel at /admin

# Hosted chat UI at /chat
chat:
  title: My Agent                  # header title
  welcome: How can I help?         # welcome message
  avatar: A                        # text avatar (1-2 chars)
  logo: https://example.com/a.png  # image avatar (overrides text)
  suggestions:                     # starter prompt buttons
    - "What can you do?"
  theme:
    primary: "#6366f1"             # brand color
  auth:
    access: approval               # open | approval (default) | invite

End-user authentication is managed by Runplex Cloud. When deployed, users sign in via Google or email/password. Access modes: open (anyone can chat), approval (admin approves, default), invite (invite-only, coming soon).

.env

# Agent API keys (passed to sandbox)
ANTHROPIC_API_KEY=sk-ant-...

# Admin access
RUNPLEX_ADMIN_TOKEN=my-secret

# Optional: more agent keys
GEMINI_API_KEY=...
LINEAR_API_KEY=...
GITHUB_TOKEN=...

.runplexignore

Exclude files from sandbox builds and deploys. Uses gitignore-style patterns.

# Large datasets
data/
*.csv

# Test fixtures
tests/
*.log

Always excluded (builtins): .env*, node_modules, .git, .runplex, runplex.yaml, *.backup. Override a builtin with negation: !.git.

Sandbox Scoping

| Scope | Behavior | |-------|----------| | user | One sandbox per user | | conversation | One per conversation/thread | | channel | One per Slack channel | | shared | One for all users |

Storage

Runplex Cloud: Storage is managed automatically (MinIO). No config needed — env vars are injected on deploy.

Self-hosted: Add a storage: section to runplex.yaml with your S3/MinIO/R2 credentials.

Storage enables:

• Session backup/restore — agent sessions survive sandbox replacements
• Mounts — file sync between storage and sandbox (tenant or user scoped)
• Memory — append-only memory that persists across sessions

Slack

Runplex Cloud: Click "Add to Slack" on your project dashboard. Zero config.

Self-hosted: Run npx runplex setup slack for guided Slack app creation.

MCP Tools

Define MCP servers in .mcp.json:

{
  "mcpServers": {
    "linear": {
      "type": "http",
      "url": "https://mcp.linear.app/mcp",
      "headers": { "Authorization": "Bearer ${LINEAR_API_KEY}" }
    }
  }
}

File Attachments

• Inbound: Upload files via chat UI or Slack → agent reads from .runplex/inbox/
• Outbound: Agent writes to .runplex/outbox/ → files appear as image previews or download cards in chat, posted to Slack

Filenames are sanitized at upload (spaces, Unicode, special characters stripped).

Architecture

Dev mode:                        Production (Cloud):
  Your laptop                      Runplex Cloud
  ├── Server (:4000)               ├── Server container
  └── Docker sandboxes             ├── Managed Redis
                                   ├── Managed Sylo
                                   └── SSL + DNS
                                   E2B
                                   └── Sandbox instances

Learn more

• Deploy Guide — full walkthrough of how Runplex works
• Starter Agents — production-ready templates to fork and customize

License

Proprietary