{"id":51168424,"url":"https://github.com/dragonforce2010/openmaple","last_synced_at":"2026-06-26T22:02:07.192Z","repository":{"id":365156621,"uuid":"1270373770","full_name":"dragonforce2010/openmaple","owner":"dragonforce2010","description":"Open-source managed-agent platform with Docker Compose local runtime/sandbox pools, sessions, vaults, SDK, CLI, and provider adapters.","archived":false,"fork":false,"pushed_at":"2026-06-23T16:01:58.000Z","size":18473,"stargazers_count":0,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-23T18:05:54.813Z","etag":null,"topics":["agent-framework","agent-platform","agent-runtime","ai-agents","ai-infrastructure","cloud-agnostic","control-plane","developer-tools","docker","docker-compose","managed-agents","mcp","multi-cloud","open-source","platform-engineering","runtime-pool","sandbox","sandboxing","self-hosted","typescript"],"latest_commit_sha":null,"homepage":"https://dragonforce2010.github.io/openmaple/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dragonforce2010.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-15T16:44:39.000Z","updated_at":"2026-06-23T16:02:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dragonforce2010/openmaple","commit_stats":null,"previous_names":["dragonforce2010/openmaple"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/dragonforce2010/openmaple","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dragonforce2010%2Fopenmaple","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dragonforce2010%2Fopenmaple/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dragonforce2010%2Fopenmaple/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dragonforce2010%2Fopenmaple/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dragonforce2010","download_url":"https://codeload.github.com/dragonforce2010/openmaple/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dragonforce2010%2Fopenmaple/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34834415,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-26T02:00:06.560Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-framework","agent-platform","agent-runtime","ai-agents","ai-infrastructure","cloud-agnostic","control-plane","developer-tools","docker","docker-compose","managed-agents","mcp","multi-cloud","open-source","platform-engineering","runtime-pool","sandbox","sandboxing","self-hosted","typescript"],"created_at":"2026-06-26T22:02:03.153Z","updated_at":"2026-06-26T22:02:07.186Z","avatar_url":"https://github.com/dragonforce2010.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenMaple\n\n[![CI](https://github.com/dragonforce2010/openmaple/actions/workflows/ci.yml/badge.svg)](https://github.com/dragonforce2010/openmaple/actions/workflows/ci.yml)\n[![GitHub Pages](https://github.com/dragonforce2010/openmaple/actions/workflows/pages.yml/badge.svg)](https://github.com/dragonforce2010/openmaple/actions/workflows/pages.yml)\n[![Release](https://img.shields.io/github/v/release/dragonforce2010/openmaple?label=release)](https://github.com/dragonforce2010/openmaple/releases/latest)\n[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/dragonforce2010/openmaple?quickstart=1)\n[![npm SDK](https://img.shields.io/npm/v/maple-agent-sdk?label=maple-agent-sdk)](https://www.npmjs.com/package/maple-agent-sdk)\n[![npm CLI](https://img.shields.io/npm/v/maple-agent-cli?label=maple-agent-cli)](https://www.npmjs.com/package/maple-agent-cli)\n\n**Open-source managed agents without cloud lock-in.**\n\nOpenMaple is an open-source managed-agent control plane for teams that want the Anthropic Managed Agents operating model without binding their stack to one cloud. It gives you sessions, sandboxes, runtime pools, vault-backed tools, model configs, SDKs, CLIs, and audit logs behind stable interfaces.\n\nOpenMaple 是开放的 managed agent 控制面：把 Session、Sandbox、Runtime Pool、Vault、Tool、模型接入点、SDK、CLI 和审计事件流放进同一套可二开的工程栈。\n\nOpenMaple is not an Anthropic official product. It implements the same platform idea in an open stack: decouple the brain from the hands, persist session state, isolate computation, and keep agent harnesses replaceable.\n\n[Website](https://dragonforce2010.github.io/openmaple/) · [Evaluation guide](EVALUATION.md) · [Provider readiness](PROVIDER_READINESS.md) · [中文 README](README.zh-CN.md) · [Roadmap](ROADMAP.md) · [Contributing](CONTRIBUTING.md) · [Support](SUPPORT.md) · [Code of Conduct](CODE_OF_CONDUCT.md) · [Security](SECURITY.md) · [Latest release](https://github.com/dragonforce2010/openmaple/releases/latest) · [Launch discussion](https://github.com/dragonforce2010/openmaple/discussions/30) · [npm CLI](https://www.npmjs.com/package/maple-agent-cli) · [npm SDK](https://www.npmjs.com/package/maple-agent-sdk)\n\n\u003cimg src=\"assets/screenshots/openmaple-quickstart.png\" alt=\"OpenMaple quickstart builder real console screenshot\"\u003e\n\n_Screenshots are public-safe captures from the running OpenMaple console. Local Docker proof shots use demo/local test identities only and do not expose secret keys._\n\nFeedback wanted: join the [launch discussion](https://github.com/dragonforce2010/openmaple/discussions/30) to challenge the resource model, provider priorities, and first proof you would need before trying OpenMaple inside an engineering team.\n\nFastest trial path: run `./scripts/setup-local-docker.sh` locally, or open [GitHub Codespaces](https://codespaces.new/dragonforce2010/openmaple?quickstart=1) and run the same setup command. You get the web console on `http://127.0.0.1:8080/`, API, MySQL, local dev login, local Docker runtime pools, and local Docker sandbox pools without E2B, veFaaS, or OAuth credentials. Model keys are only needed when you run real model-backed loops.\n\nEvaluating for an internal platform spike? Start with the [30-minute evaluation guide](EVALUATION.md).\n\nPrefer video first?\n\n\u003ca href=\"https://dragonforce2010.github.io/openmaple/#tour\"\u003e\u003cimg src=\"assets/openmaple-social-card.png\" alt=\"Watch the 2-minute OpenMaple platform tour\"\u003e\u003c/a\u003e\n\nThe [2-minute OpenMaple platform tour](https://dragonforce2010.github.io/openmaple/#tour) plays on the project site and is also available on [YouTube](https://www.youtube.com/watch?v=zYhgkFomZ7M). It is built from the running console and real end-to-end screenshots. The [local Docker walkthrough](https://dragonforce2010.github.io/openmaple/#local-docker-tour) focuses on the one-command setup, workspace settings, runtime/sandbox pools, sessions, and quickstart UI.\n\n## First Proofs\n\n| Need to verify | Start here |\n|---|---|\n| It is a real product surface, not only architecture copy | [Watch the 2-minute product tour](https://dragonforce2010.github.io/openmaple/#tour) and inspect [real console screenshots](assets/screenshots/). |\n| A local managed-agent path can start without cloud credentials | `./scripts/setup-local-docker.sh`, then open `http://127.0.0.1:8080/`. The local stack uses `local_docker` for both runtime and sandbox pools. |\n| The local Docker path is visible end to end | Watch the [local Docker walkthrough](https://dragonforce2010.github.io/openmaple/#local-docker-tour) and inspect the proof screenshots below. |\n| It has a coherent managed-agent model | Follow the [30-minute evaluation guide](EVALUATION.md). |\n| It keeps provider claims honest | Check [provider readiness](PROVIDER_READINESS.md) before assuming an adapter is production-ready. |\n| It exposes UI, API, SDK, and CLI paths | Check the [SDK](packages/sdk/), [CLI](packages/cli/), and API surface below. |\n\n## 60-Second Read\n\n- **For platform teams**: build a self-hostable managed-agent platform instead of wiring one-off agent demos.\n- **For enterprise IT**: keep cloud identity, runtime, sandbox, storage, and model access behind replaceable provider adapters.\n- **For engineering teams**: start from the web console, automate through REST, then package repeatable workflows with `maple-agent-sdk` and `maple-agent-cli`.\n- **For local evaluation**: run the console, API, MySQL, local Docker runtime pool, and local Docker sandbox pool with Docker Compose before connecting cloud credentials.\n- **For long-running agents**: keep session state outside the model context window and isolate tool execution from credentials.\n- **For contributors**: the public repo includes the console, API, SDK, CLI, provider contracts, and deployable runtime adapters.\n\n## Run It Locally\n\nStart the control plane, web console, local MySQL database, and local dev login with one command:\n\n```bash\n./scripts/setup-local-docker.sh\n```\n\nThe script checks Docker, installs missing macOS packages when possible, creates `.env.local`, starts the stack, waits for health checks, and prints the URLs.\n\nOpen:\n\n```text\nWeb console: http://127.0.0.1:8080/\nLocal login:  http://127.0.0.1:8080/?dev_login=1\nAPI health:   http://127.0.0.1:27951/health\n```\n\n\u003cimg src=\"assets/screenshots/openmaple-local-setup-terminal.png\" alt=\"OpenMaple local Docker setup terminal output showing one command, health checks, and local login URL\"\u003e\n\nThe local stack is self-contained for evaluation: it builds OpenMaple, starts separate `web`, `api`, and `mysql` services, enables local dev login, and persists data in the `mysql_data` volume. It defaults both the agent runtime provider and sandbox provider to `local_docker`, mounts the host Docker socket into the API service, and prewarms runtime/sandbox pools without E2B or veFaaS credentials. OAuth/SSO providers are hidden in local Docker mode; model keys are only needed when you run real model-backed agent loops.\n\nLocal Docker mode starts with an empty model pool and does not read host provider keys implicitly. To show a default model, copy `config/local-model.example.json` to `config/local-model.json`, set `base_url`, `model_name`, and `api_key_env`, then rerun setup. The bundled VolcoEngine presets are not seeded in local Docker mode unless you explicitly set `MAPLE_SEED_DEFAULT_MODELS=true`.\n\nOptional demo data lives in `docker/local-demo-data.sql`. Set `MAPLE_SEED_DEMO_DATA=true` before running the setup script, or set it in `.env.local`, to import two demo tenants, users, agents, runtime/sandbox pool rows, and sessions.\n\nFor host-side tests or scripts, the stack also exposes the API on `127.0.0.1:27951` and MySQL on `127.0.0.1:${MAPLE_MYSQL_HOST_PORT:-3307}`.\n\nNo local Docker setup? Open [GitHub Codespaces](https://codespaces.new/dragonforce2010/openmaple?quickstart=1), wait for the devcontainer to finish, then run `./scripts/setup-local-docker.sh` and `npm run smoke:local`. Codespaces forwards the web console and API ports for you.\n\n## Initialization and Deployment Configuration\n\nOpenMaple uses different configuration files for local evaluation and cloud deployment:\n\n| File or source | Purpose |\n|---|---|\n| `.env.local` | Generated by `./scripts/setup-local-docker.sh`. Local Docker evaluation reads this file. Do not use it as a cloud deployment template. |\n| `.env.example` | Minimal local Docker sample plus optional model-key placeholders. Online-only OAuth, veFaaS, TOS, E2B, and MCP client variables are intentionally omitted. |\n| `.env` | Host-side development or self-hosted deployment overrides. Keep service-level database, storage, OAuth, VPC, and registry settings here or in your deployment secret manager. Do not commit this file. Tenant cloud AK/SK normally comes from onboarding, not this file. |\n| Deployment environment | Production services can set the same variables through systemd, Kubernetes, Docker Compose, GitHub Actions secrets, or another secret manager. Runtime pool provisioning reads the process environment of the control-plane API. |\n\nRuntime pool provisioning creates **Agent Loop Runtime** functions. These are not sandbox functions. Runtime pool members run the agent loop (`claude_code`, `codex_open_source`, or direct model adapters). Sandbox pool members isolate tool execution and files. Configure and troubleshoot the two pools separately.\n\n### veFaaS Runtime Source Mode\n\nSource mode is the default. Leave `MAPLE_VEFAAS_IMAGE` unset or empty in the control-plane deployment environment:\n\n```env\n# MAPLE_VEFAAS_IMAGE=\n```\n\nDuring tenant onboarding, fill Volcengine `VOLCENGINE_ACCESS_KEY`, `VOLCENGINE_SECRET_KEY`, and `VEFAAS_REGION` in the cloud access step. The control plane stores those tenant credentials and passes them to runtime pool provisioning. Do not duplicate tenant AK/SK in the root `.env` for normal workspace creation.\n\nIn source mode the control plane uploads `infra/vefaas/runtime-app` as a zip package for each runtime pool member. The generated function uses `runtime=native-python3.12/v1` and `command=./run.sh`. `run.sh` starts `app.py`; the app listens on `_FAAS_RUNTIME_PORT`, then `SERVER_PORT`, then `8000`, and installs Python requirements at startup when the base runtime does not already contain them.\n\nSource mode is more portable because users do not need a container registry before first deployment. It can be slower than image mode because every function must upload source and resolve runtime dependencies.\n\n### veFaaS Runtime Image Mode\n\nSet `MAPLE_VEFAAS_IMAGE` only when the cloud account that creates veFaaS functions can read the target container image:\n\n```env\nMAPLE_VEFAAS_IMAGE=\u003cregistry-domain\u003e/\u003cnamespace\u003e/maple-runtime:\u003cversion-or-git-sha\u003e\n```\n\nIn image mode the generated function uses `source_type=image`, `runtime=native/v1`, `command=/opt/maple-runtime/run.sh`, and `port=8000`. During workspace onboarding, the control plane tries image mode first when `MAPLE_VEFAAS_IMAGE` is present. If veFaaS rejects the image, for example because the image does not exist or the account has no registry permission, provisioning falls back to source zip mode for that pool member and records the image error in the member config.\n\nRuntime pool members are provisioned concurrently. Tune the fan-out with:\n\n```env\nMAPLE_VEFAAS_RUNTIME_PROVISION_CONCURRENCY=4\n```\n\nBuild and publish a runtime image before setting `MAPLE_VEFAAS_IMAGE`:\n\n```bash\ndocker build -t maple-vefaas-runtime:ark infra/vefaas/runtime-app\n\nexport MAPLE_LOCAL_IMAGE=maple-vefaas-runtime:ark\nexport MAPLE_VEFAAS_IMAGE=\u003cregistry-domain\u003e/\u003cnamespace\u003e/maple-runtime:20260622-a1b2c3d4\n\ndocker tag \"$MAPLE_LOCAL_IMAGE\" \"$MAPLE_VEFAAS_IMAGE\"\ndocker push \"$MAPLE_VEFAAS_IMAGE\"\n```\n\nUse the full image reference accepted by veFaaS `CreateFunction` as `MAPLE_VEFAAS_IMAGE`. The final value has this shape:\n\n```text\n\u003cregistry-domain\u003e/\u003cnamespace\u003e/\u003crepository\u003e:\u003ctag\u003e\n```\n\nPrefer immutable tags such as a release version, build timestamp plus git SHA, or runtime Dockerfile hash. Avoid `latest` for shared deployments because tenants may create runtime functions against different runtime builds over time.\n\nIf you use Volcengine CR, log in to the registry domain before `docker push`. The helper script `infra/vefaas/push_and_release_runtime.py` contains the CR login, tag, push, and existing-function release flow. Its `release` step is for updating existing runtime function IDs; first-time workspace onboarding only needs the image to exist and be readable.\n\n### veFaaS Network and Resource Variables\n\nFor normal workspace onboarding, set tenant Volcengine credentials in the UI/API onboarding flow. Configure runtime-pool networking with runtime-scoped variables in the control-plane API process environment:\n\n```env\nMAPLE_VEFAAS_RUNTIME_VPC_ID=vpc-...\nMAPLE_VEFAAS_RUNTIME_SUBNET_IDS=subnet-...,subnet-...\nMAPLE_VEFAAS_RUNTIME_SECURITY_GROUP_IDS=sg-...\nMAPLE_VEFAAS_RUNTIME_ENABLE_SHARED_INTERNET_ACCESS=true\n```\n\nThe `MAPLE_VEFAAS_BACKEND_*` variables are for `infra/vefaas/deploy_vefaas_application.py`, which deploys the OpenMaple control-plane backend to veFaaS. Do not use those names as runtime pool configuration. If the deployed backend must reach MySQL through a different private endpoint, set that backend function's `MAPLE_MYSQL_HOST` during application deployment rather than duplicating host values in the root `.env`.\n\nWhen you run `infra/vefaas/deploy_vefaas_runtime.py` directly outside tenant/workspace onboarding, provide Volcengine credentials in that shell or CI job:\n\n```env\nVOLCENGINE_ACCESS_KEY=...\nVOLCENGINE_SECRET_KEY=...\nMAPLE_VEFAAS_REGION=cn-beijing\n```\n\nRuntime pool min/max instances come from the runtime pool configuration selected during workspace creation. The control plane passes them to veFaaS resource updates for each generated function. When you run `infra/vefaas/deploy_vefaas_runtime.py` directly outside workspace onboarding, these variables provide the script fallback values:\n\n```env\nMAPLE_RUNTIME_FUNCTION_MIN_INSTANCES=0\nMAPLE_RUNTIME_FUNCTION_MAX_INSTANCES=10\n```\n\nUse one `MAPLE_MYSQL_HOST` per process. A local control-plane process usually needs a public/VPN-reachable host. A deployed veFaaS control-plane backend can use a private MySQL host, but inject it as that backend process's `MAPLE_MYSQL_HOST`.\n\n### Local Docker UI Proof\n\nThese HD screenshots come from the same running local Docker stack used for the current E2E proof: setup script, dashboard, workspace settings, local runtime/sandbox pools, sessions, and quickstart. Each image is captured at `5120x2880` from the real product UI.\n\n| Setup + smoke | Demo workspace |\n|---|---|\n| \u003cimg src=\"assets/screenshots/openmaple-local-setup-terminal.png\" alt=\"OpenMaple local Docker setup terminal output showing one command, smoke checks, and local login URL\"\u003e | \u003cimg src=\"assets/screenshots/openmaple-local-dashboard.png\" alt=\"OpenMaple local Docker demo workspace dashboard screenshot\"\u003e |\n| Settings overview | Runtime provider |\n| \u003cimg src=\"assets/screenshots/openmaple-local-settings-overview.png\" alt=\"OpenMaple local Docker workspace settings overview screenshot\"\u003e | \u003cimg src=\"assets/screenshots/openmaple-local-settings-runtime.png\" alt=\"OpenMaple local Docker runtime provider settings screenshot\"\u003e |\n| Runtime pool members | Sandbox provider |\n| \u003cimg src=\"assets/screenshots/openmaple-local-runtime-pool-drawer.png\" alt=\"OpenMaple local Docker runtime pool member drawer screenshot\"\u003e | \u003cimg src=\"assets/screenshots/openmaple-local-settings-sandbox.png\" alt=\"OpenMaple local Docker sandbox provider settings screenshot\"\u003e |\n| Sandbox pool members | Sessions list |\n| \u003cimg src=\"assets/screenshots/openmaple-local-sandbox-pool-drawer.png\" alt=\"OpenMaple local Docker sandbox pool member drawer screenshot\"\u003e | \u003cimg src=\"assets/screenshots/openmaple-local-sessions-list.png\" alt=\"OpenMaple local Docker sessions list screenshot\"\u003e |\n| Session timeline | Quickstart |\n| \u003cimg src=\"assets/screenshots/openmaple-local-session-dashboard.png\" alt=\"OpenMaple local Docker session transcript and event timeline screenshot\"\u003e | \u003cimg src=\"assets/screenshots/openmaple-local-quickstart.png\" alt=\"OpenMaple local Docker quickstart builder screenshot\"\u003e |\n\n## Try the SDK Path\n\nClone the repo, fill a workspace API key plus one agent/environment pair, then run one managed-agent session through the repo SDK source:\n\n```bash\ncp examples/minimal-sdk-run/.env.example examples/minimal-sdk-run/.env\nnode examples/minimal-sdk-run/index.mjs\n```\n\nSee [examples/minimal-sdk-run](examples/minimal-sdk-run/) for required variables and expected output.\n\n## Why OpenMaple\n\nAnthropic Managed Agents turns agent deployment into a platform problem: keep the model loop, tool execution, state, credentials, sandboxing, and orchestration behind stable interfaces. OpenMaple takes that operating model and makes the control plane open, self-hostable, and provider-portable.\n\n| Managed-agent concern | OpenMaple primitive | Why it matters |\n|---|---|---|\n| Define what the agent is | `Agent` | Model, system prompt, tools, MCP servers, skills, and loop type are versioned as a managed resource. |\n| Decide where it runs | `Environment` | Separates `AgentRuntime` from `SandboxRuntime`, so reasoning and tool execution can move independently. |\n| Keep work durable | `Session` + event log | User messages, tool calls, status changes, artifacts, and failures become replayable state, not terminal scrollback. |\n| Keep secrets scoped | `Vault` + `secret_ref` | Agents receive credential references instead of raw secrets; workspaces decide which vaults sessions can use. |\n| Operate repeatably | `Deployment` | Persist an agent, environment, initial message, and schedule into a reusable launch template. |\n| Expose stable interfaces | Console, REST API, SDK, CLI | Users can start in the UI, automate with API calls, then package repeatable workflows through `maple-agent-cli`. |\n\n## Architecture\n\n```mermaid\nflowchart LR\n  subgraph Interfaces\n    Console[Web Console]\n    CLI[Maple CLI]\n    SDK[Node SDK]\n    REST[REST API]\n  end\n\n  subgraph Control[\"Control Plane\"]\n    API[Express API]\n    DB[(Remote MySQL)]\n    Vault[Vault + Secret Store]\n    Events[Session Event Log]\n  end\n\n  subgraph Runtime[\"Runtime Plane\"]\n    Claude[Claude Code Loop]\n    Codex[Codex Loop]\n    Direct[Direct Provider Loop]\n    Pool[Runtime Pool]\n  end\n\n  subgraph Sandbox[\"Sandbox Plane\"]\n    E2B[E2B]\n    VeFaaS[veFaaS Sandbox]\n    Docker[Local Docker]\n  end\n\n  Console --\u003e API\n  CLI --\u003e API\n  SDK --\u003e API\n  REST --\u003e API\n  API --\u003e DB\n  API --\u003e Vault\n  API --\u003e Events\n  API --\u003e Pool\n  Pool --\u003e Claude\n  Pool --\u003e Codex\n  Pool --\u003e Direct\n  Claude --\u003e Sandbox\n  Codex --\u003e Sandbox\n  Direct --\u003e Sandbox\n  Sandbox --\u003e E2B\n  Sandbox --\u003e VeFaaS\n  Sandbox --\u003e Docker\n```\n\n### Resource Lifecycle\n\n1. **Create an agent**: `POST /v1/agents` stores the model, prompt, tools, MCP servers, skills, and loop adapter.\n2. **Attach an environment**: `POST /v1/environments` chooses runtime provider, sandbox provider, networking, and runtime pool behavior.\n3. **Add tool credentials**: `POST /v1/vaults/:vaultId/credentials` writes encrypted secret material and returns credential references.\n4. **Start a session**: `POST /v1/sessions` binds `agent`, `environment_id`, optional `vault_ids`, resources, and metadata.\n5. **Send and stream work**: `POST /v1/sessions/:sessionId/events` writes user/tool events; `GET /v1/sessions/:sessionId/events/stream` exposes the live timeline.\n6. **Operate repeatably**: `POST /v1/deployments` saves the same launch path as a manual or scheduled run template.\n\n### API Surface\n\n| Area | Endpoints | Notes |\n|---|---|---|\n| Auth/bootstrap | `/v1/auth/*`, `/v1/bootstrap`, `/v1/console_snapshot` | Cookie or API-key auth; list endpoints are workspace-scoped. |\n| Agents | `/v1/agents`, `/v1/agents/:agentId/versions`, `/v1/agents/:agentId/runtime` | Agent configs are versioned and runtime state is inspectable. |\n| Environments | `/v1/environments`, `/v1/workspaces/:workspaceId/runtime_pool`, `/v1/workspaces/:workspaceId/sandbox_pool` | Runtime pool members provision in the background. |\n| Sessions | `/v1/sessions`, `/v1/sessions/:sessionId/events`, `/v1/sessions/:sessionId/events/stream` | Durable event log for user, agent, tool, artifact, and failure records. |\n| Vaults + MCP | `/v1/vaults`, `/v1/vaults/:vaultId/credentials`, `/v1/mcp_servers`, `/v1/mcp_servers/:mcpId/oauth/start` | OAuth and API-key credentials stay workspace-scoped. |\n| Deployments | `/v1/deployments`, `/v1/deployments/:deploymentId/run`, `/v1/deployments/:deploymentId/invoke` | Reusable launch templates with manual and scheduled execution. |\n| Files + artifacts | `/v1/files`, `/v1/sessions/:sessionId/files`, `/v1/sessions/:sessionId/artifacts` | Session file uploads and downloadable artifacts. |\n| Skills + memory | `/v1/skills`, `/v1/memory_stores`, `/v1/memory_stores/:memoryStoreId/memories/*path` | Packaged instructions and workspace-scoped persistent memory. |\n\n## What You Can Verify Today\n\n| Claim | Evidence |\n|---|---|\n| Control plane is implemented | Express routes under `apps/control-plane-api/src/routes/` and typed SDK calls in `packages/sdk/`. |\n| Runtime and sandbox are separate | Environment and runtime pool contracts, veFaaS/E2B/Docker provider paths, and session event streaming. |\n| API, SDK, and CLI are first-class | `maple-agent-sdk`, `maple-agent-cli`, route contracts, and package tests. |\n| Provider lock-in is not the model | Runtime, sandbox, storage, model, and cloud identity are represented as provider choices. |\n\n### Runtime Boundary\n\n- **Brain/hands split**: agent loops run through runtime adapters; commands, files, and network access run through sandbox providers.\n- **Secret isolation**: secrets are stored through `secret_ref` records; agents receive references and scoped tool access, not plaintext keys in config.\n- **Workspace scoping**: every list route must filter through the user's accessible workspaces. No global table scans in user-facing APIs.\n- **Remote MySQL**: the control-plane data store uses a MySQL worker bridge with pooled remote connections.\n- **Provider portability**: veFaaS, E2B, Docker, and future Lambda/FC-style runtimes can sit behind the same session contract.\n\n## Product Surface\n\n| Quickstart builder | Agents registry |\n|---|---|\n| \u003cimg src=\"assets/screenshots/openmaple-quickstart.png\" alt=\"OpenMaple quickstart builder screenshot\"\u003e | \u003cimg src=\"assets/screenshots/openmaple-agents.png\" alt=\"OpenMaple agents registry screenshot\"\u003e |\n| Runtime environments | Credential vaults |\n| \u003cimg src=\"assets/screenshots/openmaple-environments.png\" alt=\"OpenMaple environments screenshot\"\u003e | \u003cimg src=\"assets/screenshots/openmaple-vaults.png\" alt=\"OpenMaple credential vaults screenshot\"\u003e |\n\n- **Quickstart**: generate an agent draft, bind an environment, attach vaults, and start a session.\n- **Agents**: version agent configs, tools, MCP servers, skills, models, and loop type.\n- **Deployments**: persist reusable launch templates and invoke them through API/CLI/SDK paths.\n- **Sessions**: inspect transcript, event log, status, runtime metadata, files, and artifacts.\n- **Environments**: configure runtime provider, sandbox provider, pool behavior, and workspace defaults.\n- **Vaults**: attach credentials by reference without exposing raw secret material in API responses.\n\n## Repository Map\n\n```text\napps/admin-web/             React console, docs view, route sync, design system\napps/control-plane-api/     Express API, auth, storage, runtime orchestration\npackages/sdk/               Node SDK: MapleClient and typed API helpers\npackages/cli/               Maple CLI: init, build, deploy, api, session, vault\nagents/                     Packaged agent skills and runtime-facing assets\ntests/contracts/            Contract tests for docs, routes, branding, runtime behavior\n```\n\n## Local Development\n\n```bash\nbun install\nbun run dev\n```\n\nOpen:\n\n```text\nWeb Console: http://127.0.0.1:8080/\nAPI Server:  http://127.0.0.1:27951/\n```\n\nVerify:\n\n```bash\nbun run typecheck\nbun run lint\nbun run build\n```\n\nLocal Docker stack:\n\n```bash\n./scripts/setup-local-docker.sh\nnpm run smoke:local -- --base http://127.0.0.1:27951\ncurl http://127.0.0.1:27951/health\ncurl http://127.0.0.1:8080/health\n```\n\nThe local stack runs `web`, `api`, and `mysql` as separate services. `.env.example` contains only local Docker settings and optional model keys; online-only OAuth, veFaaS, TOS, E2B, and MCP client variables are intentionally omitted from the default local setup.\n\n## CLI\n\n```bash\nnpm install -g maple-agent-cli\nmaple config set api.baseUrl http://127.0.0.1:27951\nmaple config login --api-key \u003cmaple_ws_...\u003e\nmaple init --name repo-auditor --loop codex_open_source --runtime e2b --yes\nmaple build --project ./repo-auditor\nmaple deploy --project ./repo-auditor --json\n```\n\n## SDK\n\n```bash\nnpm install maple-agent-sdk\n```\n\n```ts\nimport { MapleClient } from \"maple-agent-sdk\";\n\nconst client = new MapleClient({\n  baseUrl: process.env.MAPLE_BASE_URL,\n  apiKey: process.env.MAPLE_API_KEY\n});\n\nconst { session, done } = await client.createSessionAndStream({\n  agent: \"agent_...\",\n  environment_id: \"env_...\",\n  vault_ids: [\"vault_...\"],\n  message: \"Audit this repository and summarize the risky files.\"\n});\n\nawait client.sendSessionMessage(session.id, \"Focus on auth and storage code paths.\");\nawait done;\n```\n\n## More\n\n- Managed Agents platform pattern: [Anthropic engineering essay](https://www.anthropic.com/engineering/managed-agents)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdragonforce2010%2Fopenmaple","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdragonforce2010%2Fopenmaple","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdragonforce2010%2Fopenmaple/lists"}