Computer (Python) Overview
AI orchestration server built with FastAPI. Manages agent execution with trust-level enforcement, session persistence, Claude SDK integration, modular architecture, and bot connectors for Telegram and Discord.
81
Python Files
~90
API Endpoints
8
DB Tables
19
Route Files
Directory Structure
parachute/
├── api/ # FastAPI route handlers (19 files)
│ ├── auth.py # API key management
│ ├── bots.py # Bot connector management
│ ├── chat.py # Streaming chat endpoint
│ ├── claude_code.py # Claude Code integration
│ ├── context_folders.py # Context folder management
│ ├── filesystem.py # File operations
│ ├── health.py # Health check
│ ├── hooks.py # Event hook management
│ ├── imports.py # Data import endpoints
│ ├── mcp.py # MCP server management
│ ├── modules.py # Module prompts and config
│ ├── prompts.py # Prompt management
│ ├── sandbox.py # Docker sandbox management
│ ├── scheduler.py # Agent scheduling
│ ├── sessions.py # Session CRUD + config
│ ├── skills.py # Skill plugins
│ ├── sync.py # Cross-device sync
│ ├── usage.py # Usage tracking
│ └── workspaces.py # Workspace management
├── connectors/ # Bot platform connectors
│ ├── base.py # Abstract BotConnector base class
│ ├── telegram.py # Telegram bot (streaming, voice, groups)
│ ├── discord_bot.py # Discord bot (slash commands, groups)
│ ├── config.py # Bot config from bots.yaml
│ └── message_formatter.py # Claude → platform formatting
├── core/ # Business logic
│ ├── orchestrator.py # Central agent controller
│ ├── orchestrator_tools.py # Tool definitions for orchestrator
│ ├── session_manager.py # Session persistence
│ ├── claude_sdk.py # SDK wrapper
│ ├── claude_usage.py # Token usage tracking
│ ├── module_loader.py # Module discovery + hash verification
│ ├── sandbox.py # Docker container execution
│ ├── agents.py # Agent discovery
│ ├── skills.py # Skill plugins
│ ├── scheduler.py # APScheduler wrapper
│ ├── permission_handler.py # Permission grants/denies
│ ├── capability_filter.py # Trust-level capability filtering
│ ├── workspaces.py # Workspace logic
│ ├── context_folders.py # Context folder logic
│ ├── context_parser.py # Context parsing
│ ├── chat_log.py # Chat log utilities
│ ├── daily_agent.py # Daily agent execution
│ ├── daily_agent_tools.py # Daily agent tool definitions
│ ├── import_service.py # Data import logic
│ ├── interfaces.py # Abstract interfaces
│ └── hooks/ # Event hook system
│ ├── runner.py # Hook discovery + execution
│ ├── events.py # Event type definitions
│ └── models.py # Hook data models
├── db/ # SQLite database layer
│ └── database.py # aiosqlite + schema (8 tables)
├── docker/ # Sandbox infrastructure
│ ├── Dockerfile.sandbox # Sandbox container image
│ └── entrypoint.py # Container entrypoint
├── lib/ # Utilities
│ ├── agent_loader.py # Load agents from markdown
│ ├── auth.py # API key generation
│ ├── context_loader.py # Format context for prompts
│ ├── ignore_patterns.py # .gitignore-style filtering
│ ├── logger.py # Logging setup
│ ├── mcp_loader.py # MCP server config
│ ├── para_id.py # Para-ID generation
│ ├── permissions.py # Permission utilities
│ ├── server_config.py # Auth modes + config
│ ├── typed_errors.py # Error types
│ └── vault_utils.py # Vault path utilities
├── models/ # Pydantic models
│ ├── session.py # Session + SessionCreate
│ ├── requests.py # API request models
│ ├── agent.py # Agent definitions
│ ├── events.py # SSE event types
│ └── workspace.py # Workspace models
├── hooks/ # Built-in hooks
│ └── activity_hook.py # Activity tracking hook
├── config.py # Settings (env > .env > YAML > defaults)
├── server.py # FastAPI app + lifespan
├── cli.py # CLI (install/update/server/logs/doctor/config/module)
├── daemon.py # Daemon management (launchd/systemd/PID)
└── mcp_server.py # MCP protocol server
Request Flow
┌──────────────────────────────────────┐
│ HTTP Request │
│ POST /api/chat {"message": "..."} │
└────────────────┬─────────────────────┘
│
┌────────────────▼─────────────────────┐
│ Auth Middleware │
│ - Check auth mode (remote/always) │
│ - Validate API key or localhost │
└────────────────┬─────────────────────┘
│
┌────────────────▼─────────────────────┐
│ API Router │
│ api/chat.py │
│ │
│ - Validate request │
│ - Resolve session + workspace │
│ - Call orchestrator │
└────────────────┬─────────────────────┘
│
┌────────────────▼─────────────────────┐
│ Orchestrator │
│ core/orchestrator.py │
│ │
│ - Enforce trust level │
│ - Load module system prompt │
│ - Build context (folders, history) │
│ - Route to SDK or Docker sandbox │
└────────────────┬─────────────────────┘
│
┌────────────────────────────────┼────────────────────────────┐
│ │ │
▼ ▼ ▼
┌──────────────────────┐ ┌───────────────────────┐ ┌──────────────────────┐
│ Trust: full / vault │ │ Trust: sandboxed │ │ Session Manager │
│ │ │ │ │ │
│ Claude SDK │ │ Docker Sandbox │ │ - Create/update │
│ (direct execution) │ │ (container isolation) │ │ - Query DB │
│ core/claude_sdk.py │ │ core/sandbox.py │ │ - SDK ID mapping │
└──────────┬───────────┘ └───────────┬────────────┘ └──────────────────────┘
│ │
└──────────┬─────────────────┘
│
▼
┌────────────────────┐
│ Claude AI │
│ (Anthropic) │
└─────────┬──────────┘
│
┌─────────────▼───────────────────────┐
│ SSE Response │
│ StreamingResponse (async gen) │
│ │
│ data: {"type": "text", ...} │
│ data: {"type": "tool_use", ...} │
│ data: {"type": "result", ...} │
└──────────────────────────────────────┘
Key Components
Orchestrator
Central agent controller. Routes requests through trust-level enforcement, builds context, manages SDK/sandbox execution, and streams SSE events.
Learn more →Module Loader
Discovers modules from vault/.modules/, verifies SHA-256 hashes, registers API routes. Modules: brain (search), chat, daily.
Learn more →Trust Levels
Three tiers: full (unrestricted), vault (directory-restricted), sandboxed (Docker). Enforced per-session with workspace-level floors.
Learn more →Session Manager
CRUD for SQLite session metadata. Maps SDK session IDs to database records. Handles working directory and context tracking.
Learn more →Bot Connectors
Telegram and Discord bridges. Streaming responses, ack reactions, group history injection, user pairing/approval, per-chat settings.
Learn more →Docker Sandbox
Container-based isolation for sandboxed sessions. Each execution runs in a fresh container with vault mounted read-only.
Learn more →Server Lifecycle
The lifespan manager in server.py initializes all services on startup:
- Logging — Configure from settings
- Server config — Load API keys and auth settings
- Database — Initialize SQLite at
vault/Chat/sessions.db - Orchestrator — Create with vault path, DB, and settings
- Scheduler — APScheduler for automated agents
- Module Loader — Discover, verify hashes, register routes
- Hooks — Discover hook scripts in
vault/.parachute/hooks/ - Bot connectors — Auto-start enabled connectors from
bots.yaml
On shutdown: stop bots, stop scheduler, close database.
Authentication
Two layers of authentication:
Claude SDK Auth
CLAUDE_CODE_OAUTH_TOKEN — long-lived OAuth token from claude setup-token. Stored at vault/.parachute/.token. Required for all AI chat functionality.
API Key Auth
For multi-device access to the server:
| Mode | Behavior | Use Case |
|---|---|---|
disabled |
No auth required | Local-only development |
remote (default) |
Localhost bypasses, remote requires key | Normal usage |
always |
All requests require valid API key | Shared server |
Keys are managed via POST /api/auth/keys, GET /api/auth/keys, DELETE /api/auth/keys/{key_id}. Keys are SHA-256 hashed before storage in server-config.json.
Configuration
Config precedence: env vars > .env file > vault/.parachute/config.yaml > defaults.
| Setting | Env Var | Default | Description |
|---|---|---|---|
vault_path |
VAULT_PATH |
./sample-vault |
Path to vault directory |
port |
PORT |
3333 |
Server port |
host |
HOST |
0.0.0.0 |
Bind address |
claude_code_oauth_token |
CLAUDE_CODE_OAUTH_TOKEN |
— | OAuth token (also from .token file) |
default_model |
DEFAULT_MODEL |
— | Optional model override |
auth_mode |
AUTH_MODE |
remote |
Auth mode: remote / always / disabled |
log_level |
LOG_LEVEL |
INFO |
Logging verbosity |
cors_origins |
CORS_ORIGINS |
* |
Allowed CORS origins |
debug |
DEBUG |
false |
Enable debug mode |
Manage via CLI: parachute config show, parachute config set KEY VAL, parachute config get KEY.
Running the Server
CLI Commands
# First-time install (venv + deps + config + daemon)
cd computer && ./install.sh
# Manage the daemon
parachute server status # Check if running
parachute server stop # Stop daemon
parachute server restart # Restart daemon
parachute server -f # Run in foreground (dev mode)
# Logs and diagnostics
parachute logs # Tail daemon logs
parachute status # System overview
parachute doctor # Run diagnostics
# Module management
parachute module list # List modules + approval status
parachute module approve NAME # Approve a module (record hash)
parachute module status # Live module status (requires running server)
# Updates
parachute update # Pull latest + reinstall + restart
parachute update --local # Reinstall + restart (skip git pull)
# Or run directly
source .venv/bin/activate
VAULT_PATH=./vault uvicorn parachute.server:app --port 3333Key Dependencies
| Package | Purpose |
|---|---|
fastapi / uvicorn |
Web framework + ASGI server |
pydantic / pydantic-settings |
Data validation + config management |
aiosqlite |
Async SQLite driver |
claude-agent-sdk |
Claude AI integration |
sse-starlette |
Server-Sent Events streaming |
python-telegram-bot |
Telegram bot connector |
discord.py |
Discord bot connector |
aiodocker |
Docker sandbox management |
apscheduler |
Cron-based agent scheduling |
python-frontmatter |
Markdown frontmatter parsing |
pyyaml |
YAML config + module manifests |