marionette

module
v0.0.0-...-1bb08d0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 15, 2026 License: MIT

README

Marionette

A remote agent orchestration and observability platform for controlling coding agents (Claude Code, Codex, etc.) running in isolated environments.

Features

  • Multi-Agent Support - Run Claude Code, Codex, or custom agents
  • Flexible Deployment - Docker, Kubernetes, E2B, Firecracker, or bare metal pools
  • Session Management - Long-lived work contexts with suspend/resume
  • Workspace Persistence - Encrypted storage with S3/GCS sync
  • Real-time Streaming - Live logs, permission requests, progress updates
  • Port Forwarding - HTTP tunnels, desktop streaming (WebRTC), iOS/Android emulator
  • Multi-tenant - Built for SaaS integration with tenant isolation

Quick Start

Prerequisites
  • Go 1.22+
  • PostgreSQL 15+
  • Docker (for local development)
Installation
# Clone repository
git clone https://github.com/chunlea/marionette.git
cd marionette

# Install dependencies
make deps

# Setup database
createdb marionette
make migrate

# Build binaries
make build
Running Locally
# Terminal 1: Start server
./bin/server --config configs/local.yaml

# Terminal 2: Start a Docker runner
./bin/agent --server localhost:9090 --token dev-token

# Terminal 3: Use CLI
./bin/mctl sessions create --agent claude --api-key $ANTHROPIC_API_KEY
./bin/mctl tasks create --session $SESSION_ID --prompt "Build a REST API"
./bin/mctl tasks logs --follow $TASK_ID
Docker Compose
docker compose up -d

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                           Server (Go)                               │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐    │
│  │ SessionMgr  │ │  TaskMgr    │ │ RunnerMgr   │ │ TunnelMgr   │    │
│  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘    │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │  Provider Registry (Docker, K8s, E2B, Pool, ...)            │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                              │                                      │
│  :9090 gRPC  │  :8080 Public API  │  :8081 Admin UI                 │
└──────────────┼────────────────────┼─────────────────────────────────┘
               │                    │
               ▼                    ▼
┌──────────────────────┐    ┌──────────────────────┐
│  Runner (isolated)   │    │  Runner (pool)       │
│  ┌────────────────┐  │    │  ┌────────────────┐  │
│  │marionette-agent│  │    │  │marionette-agent│  │
│  │ ┌────────────┐ │  │    │  └───────┬────────┘  │
│  │ │Claude Code │ │  │    │          │           │
│  │ └────────────┘ │  │    │  ┌───────▼────────┐  │
│  │ ┌────────────┐ │  │    │  │Sandbox (gVisor)│  │
│  │ │ /workspace │ │  │    │  │ Agent+Workspace│  │
│  │ └────────────┘ │  │    │  └────────────────┘  │
│  └────────────────┘  │    └──────────────────────┘
└──────────────────────┘

Core Concepts

Concept Description
Runner Execution environment (container, VM, or machine)
Session Long-lived work context binding Runner + Workspace
Task Unit of work (prompt) executed within a Session
Workspace Persistent /workspace directory
Agent AI coding agent (Claude Code, Codex, etc.)

API Usage

Create a Session
curl -X POST http://localhost:8080/api/v1/sessions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "claude",
    "api_key": "sk-ant-xxx",
    "labels": {"user": "alice", "project": "my-app"}
  }'
Submit a Task
curl -X POST http://localhost:8080/api/v1/sessions/$SESSION_ID/tasks \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Build a REST API with authentication"}'
Stream Logs
curl -N http://localhost:8080/api/v1/tasks/$TASK_ID/logs?follow=true \
  -H "Authorization: Bearer $API_KEY"

Configuration

# config.yaml - non-sensitive settings only
server:
  api:
    port: 8080
  admin:
    port: 8081
  grpc:
    port: 9090

providers:
  default: docker
  docker:
    image: "ghcr.io/chunlea/marionette-runner:latest"

storage:
  provider: local
  local:
    path: /var/marionette/storage

# .env - sensitive values (all prefixed with MARIONETTE_)
MARIONETTE_DATABASE_URL=postgres://localhost/marionette?sslmode=disable
MARIONETTE_MASTER_KEY=your-master-key
MARIONETTE_ENCRYPTION_KEY=your-encryption-key

Documentation

Document Description
CLAUDE.md Complete architecture and design
docs/schema.sql Database schema
docs/id.md ID generation (Stripe-style)
docs/runner.proto gRPC protocol
docs/storage.md Storage, CAS, and encryption
docs/agents.md Agent plugin architecture
docs/pool.md Pool runners and watchdog
docs/roadmap.md Implementation phases

CLI Reference

# Sessions
mctl sessions list
mctl sessions create --agent claude --api-key $KEY
mctl sessions suspend $SESSION_ID
mctl sessions resume $SESSION_ID --api-key $KEY
mctl sessions terminate $SESSION_ID

# Tasks
mctl tasks create --session $SID --prompt "Fix the bug"
mctl tasks list --session $SID
mctl tasks logs --follow $TASK_ID
mctl tasks cancel $TASK_ID

# Runners
mctl runners list
mctl runners get $RUNNER_ID
mctl runners pause $RUNNER_ID
mctl runners resume $RUNNER_ID

# Tunnels
mctl tunnels create --session $SID --type http --port 3000
mctl tunnels list --session $SID

Development

# Run tests
make test

# Run linter
make lint

# Generate protobuf
make proto

# Build Docker image
make docker-build

# Run with hot reload
make dev

Environment Variables

Variable Description Default
MARIONETTE_CONFIG Config file path config.yaml
MARIONETTE_DATABASE_URL PostgreSQL connection string -
MARIONETTE_MASTER_KEY Master key for admin operations -
MARIONETTE_ENCRYPTION_KEY Key for encrypting agent credentials -
MARIONETTE_LOG_LEVEL Log level info

License

MIT

Directories

Path Synopsis
cmd
agent command
Package main provides the marionette-agent binary.
 Package main provides the marionette-agent binary.
mctl command
Package main provides the mctl CLI binary.
 Package main provides the mctl CLI binary.
server command
Package main provides the marionette server binary.
 Package main provides the marionette server binary.
pkg
agent
Package agent provides the marionette-agent implementation.
 Package agent provides the marionette-agent implementation.
agent/executor
Package executor provides interfaces and implementations for running AI agents.
 Package executor provides interfaces and implementations for running AI agents.
agent/executor/claude
Package claude implements the executor for Claude Code CLI.
 Package claude implements the executor for Claude Code CLI.
audit
Package audit provides audit logging capabilities for tracking sensitive actions.
 Package audit provides audit logging capabilities for tracking sensitive actions.
auth
Package auth provides authentication services for Marionette.
 Package auth provides authentication services for Marionette.
client
Package client provides a client interface for the Marionette API.
 Package client provides a client interface for the Marionette API.
config
Package config provides configuration loading and validation for the Marionette server.
 Package config provides configuration loading and validation for the Marionette server.
crypto/certreloader
Package certreloader provides automatic certificate reloading for TLS connections.
 Package certreloader provides automatic certificate reloading for TLS connections.
cryptoutil
Package cryptoutil provides cryptographic utilities for Marionette.
 Package cryptoutil provides cryptographic utilities for Marionette.
id
Package id provides Stripe-style prefixed ID generation for Marionette resources.
 Package id provides Stripe-style prefixed ID generation for Marionette resources.
jobs
Package jobs provides background job implementations for the marionette server.
 Package jobs provides background job implementations for the marionette server.
network
Package network provides network policy types and enforcement for session isolation.
 Package network provides network policy types and enforcement for session isolation.
network/iptables
Package iptables provides iptables rule generation and management for network isolation.
 Package iptables provides iptables rule generation and management for network isolation.
observability/health
Package health provides health check infrastructure for Kubernetes probes.
 Package health provides health check infrastructure for Kubernetes probes.
observability/metrics
Package metrics provides Prometheus metrics for the Marionette server.
 Package metrics provides Prometheus metrics for the Marionette server.
observability/trace
Package trace provides OpenTelemetry tracing for the Marionette server.
 Package trace provides OpenTelemetry tracing for the Marionette server.
provider
Package provider defines interfaces for managing runner lifecycle across different infrastructure backends (Docker, Kubernetes, E2B, etc.).
 Package provider defines interfaces for managing runner lifecycle across different infrastructure backends (Docker, Kubernetes, E2B, etc.).
provider/docker
Package docker implements a Docker container provider for Marionette.
 Package docker implements a Docker container provider for Marionette.
provider/e2b
provider/kubernetes
Package kubernetes implements a Kubernetes pod provider for Marionette.
 Package kubernetes implements a Kubernetes pod provider for Marionette.
provider/pool
Package pool implements a pool-based provider for Marionette.
 Package pool implements a pool-based provider for Marionette.
sandbox
Package sandbox provides sandbox detection, verification, and resource limit enforcement.
 Package sandbox provides sandbox detection, verification, and resource limit enforcement.
server/admin
Package admin provides the admin HTTP API server.
 Package admin provides the admin HTTP API server.
server/api
Package api provides the public HTTP API server for Marionette.
 Package api provides the public HTTP API server for Marionette.
server/core
Package core provides business logic for the Marionette server.
 Package core provides business logic for the Marionette server.
server/grpc
Package grpc provides the gRPC server for runner communication.
 Package grpc provides the gRPC server for runner communication.
storage
Package storage provides interfaces and implementations for blob storage.
 Package storage provides interfaces and implementations for blob storage.
storage/cas
Package cas provides Content-Addressable Storage for workspace synchronization.
 Package cas provides Content-Addressable Storage for workspace synchronization.
store
Package store provides the persistence interface and data models for Marionette.
 Package store provides the persistence interface and data models for Marionette.
store/mock
Package mock provides in-memory mock implementations of store interfaces for testing.
 Package mock provides in-memory mock implementations of store interfaces for testing.
store/postgres
Package postgres implements the store.Store interface using PostgreSQL.
 Package postgres implements the store.Store interface using PostgreSQL.
streaming
Package streaming provides unified streaming infrastructure for Marionette.
 Package streaming provides unified streaming infrastructure for Marionette.
streaming/android
Package android provides Android device streaming and input forwarding capabilities.
 Package android provides Android device streaming and input forwarding capabilities.
streaming/android/scrcpy
Package scrcpy provides an Android streaming provider using scrcpy.
 Package scrcpy provides an Android streaming provider using scrcpy.
streaming/browser
Package browser provides browser streaming infrastructure for Marionette.
 Package browser provides browser streaming infrastructure for Marionette.
streaming/desktop
Package desktop provides desktop streaming implementations using WebRTC.
 Package desktop provides desktop streaming implementations using WebRTC.
streaming/manager
Package manager provides the streaming Manager which coordinates providers, the SFU, and stream persistence.
 Package manager provides the streaming Manager which coordinates providers, the SFU, and stream persistence.
streaming/sfu
Package sfu implements a Selective Forwarding Unit (SFU) for WebRTC media streaming.
 Package sfu implements a Selective Forwarding Unit (SFU) for WebRTC media streaming.
tunnel
Package tunnel provides HTTP/TCP tunneling support for Marionette.
 Package tunnel provides HTTP/TCP tunneling support for Marionette.
webhook
Package webhook provides webhook delivery functionality for external system integration.
 Package webhook provides webhook delivery functionality for external system integration.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.