mirror of
https://github.com/tinyhumansai/openhuman.git
synced 2026-07-28 05:12:33 +00:00
100 lines
3.9 KiB
Markdown
100 lines
3.9 KiB
Markdown
# AgentBox Marketplace Deployment
|
||
|
||
OpenHuman ships as a containerized agent on GMI Cloud's
|
||
[AgentBox marketplace](https://docs.gmicloud.ai/agentbox-marketplace/overview).
|
||
This page is the operator runbook for new deployments and version bumps.
|
||
|
||
## Container contract
|
||
|
||
When `OPENHUMAN_AGENTBOX_MODE=1`, the core HTTP server exposes:
|
||
|
||
- `POST /run` — accept work, return `202 { "job_id": "<uuid>" }`. Body shape:
|
||
`{ "payload": { "message": "<string>", "thread_id": "<optional string>" } }`.
|
||
- `GET /jobs/{job_id}` — return `{ "status": "pending|running|completed|failed", "result": ..., "error": ... }`.
|
||
- `GET /health` — liveness.
|
||
|
||
Both `/run` and `/jobs/*` are unauthenticated at the container boundary —
|
||
AgentBox's edge handles auth before traffic reaches us.
|
||
|
||
## The 4-step register wizard
|
||
|
||
In the AgentBox console:
|
||
|
||
1. **Basic Info** — name `OpenHuman`, description, listing identity.
|
||
2. **Infrastructure** — Docker image source (push tagged builds to your
|
||
chosen registry, see "Image push" below), compute tier, region. Enable the
|
||
"GMI MaaS" toggle so the platform injects `GMI_MAAS_BASE_URL` and
|
||
`GMI_MAAS_API_KEY` at runtime.
|
||
3. **Env Variables** — set:
|
||
- `OPENHUMAN_AGENTBOX_MODE=1`
|
||
- (optional) `OPENHUMAN_AGENTBOX_JOB_TIMEOUT_SECS` (default 600)
|
||
- `GMI_MODELS` to the marketplace-approved model id (e.g.
|
||
`deepseek-ai/DeepSeek-V4-Pro`).
|
||
- `OPENHUMAN_WORKSPACE` to a writable container path (e.g. `/home/openhuman/.openhuman`).
|
||
- `RUST_LOG=info` (or `debug` while shaking out the first deploy).
|
||
4. **Review & Register** — confirm and test from the console panel.
|
||
|
||
> ⚠️ The platform API key is shown ONCE on the registration confirmation
|
||
> screen. Save it to your secrets manager immediately. It is NOT recoverable
|
||
> from the console after that.
|
||
|
||
## Image push
|
||
|
||
Build and push from `main` using the existing `Dockerfile`:
|
||
|
||
```bash
|
||
docker build -t <registry>/openhuman-core:<tag> .
|
||
docker push <registry>/openhuman-core:<tag>
|
||
```
|
||
|
||
First deploy takes 10–25 minutes to reach `running`; later deploys are faster.
|
||
|
||
## Long-running requests
|
||
|
||
AgentBox treats requests >2 min as long-running. OpenHuman handles this with
|
||
**polling** per AgentBox's documented pattern — the agent runtime is invoked
|
||
inside the worker task, capped by `OPENHUMAN_AGENTBOX_JOB_TIMEOUT_SECS`
|
||
(default 10 minutes). No streaming.
|
||
|
||
Polling clients should:
|
||
|
||
1. `POST /run` and capture `job_id`.
|
||
2. `GET /jobs/{job_id}` every 1–3 seconds.
|
||
3. Stop when `status` is `completed` or `failed`.
|
||
4. Note: terminal jobs are retained for 1 hour after completion, then
|
||
garbage-collected. Long pauses between poll and read may return `404`.
|
||
|
||
## Local smoke test
|
||
|
||
```bash
|
||
OPENHUMAN_AGENTBOX_MODE=1 \
|
||
GMI_MAAS_BASE_URL=https://api.gmi-serving.com \
|
||
GMI_MAAS_API_KEY=sk-... \
|
||
GMI_MODELS=deepseek-ai/DeepSeek-V4-Pro \
|
||
./target/debug/openhuman-core serve &
|
||
|
||
curl -X POST http://127.0.0.1:7788/run \
|
||
-H 'content-type: application/json' \
|
||
-d '{"payload":{"message":"hello"}}'
|
||
|
||
# Then poll the returned job_id:
|
||
curl http://127.0.0.1:7788/jobs/<job_id>
|
||
```
|
||
|
||
## Troubleshooting
|
||
|
||
- `404 job not found` after a successful submit — retention window (1h) has
|
||
elapsed, or the container restarted (in-memory store is not durable in v1).
|
||
- `status: "failed"`, `error: "agentbox: agent runtime bridge not wired"` —
|
||
the production invoker stub from before Task 9 landed; rebuild against a
|
||
current `main`.
|
||
- `status: "failed"`, `error: "job timeout after Ns"` — the agent invocation
|
||
exceeded `OPENHUMAN_AGENTBOX_JOB_TIMEOUT_SECS`. Bump the env var on the
|
||
next deploy.
|
||
- `[agentbox::gmi] not registering GMI MaaS provider: missing/blank: GMI_MAAS_API_KEY` —
|
||
the platform did not inject the key. Re-check the wizard's "MaaS
|
||
integration toggle" in Step 2.
|
||
- `[agentbox::gmi] current-thread runtime detected — skipping provider registration` —
|
||
the core was booted in a single-threaded tokio runtime. Use the standard
|
||
`serve` subcommand, which spawns a multi-thread runtime.
|