@gencode/server

One-shot AIMax container prestart server.

This package starts a local HTTP process that warms system-level runtime state, accepts exactly one /run request, executes the task, and exits when the run finishes.

Usage

aimax-server --host 127.0.0.1 --port 0 --plugins-config /image/aimax/plugins.json

--plugins-config can also be supplied as AIMAX_SERVER_PLUGINS_CONFIG. The server reads that file during warmup and preloads the configured system plugins.

Execution paths

POST /run supports two execution branches:

• Without engine, or with engine type aimax (default): delegates to @gencode/cli/run.executeRun(). If the accepted request does not provide run.pluginsConfig and does not override AIMAX_PLUGINS_CONFIG in request env, the run inherits the startup plugins config path so the CLI execution uses the preloaded plugin registry.
• With a Uni engine type: delegates to @gencode/uni.executeUniRun(). The server merges run with the selected engine type and optional engine.runtimeConfig, removes uni-unsupported fields via omitUnsupportedUniRunOptions(), and does not inherit startup pluginsConfig or call the CLI run path.

Request shape:

type ServerRunRequest = {
  env?: Record<string, string | number | boolean | null>;
  run: RunOptions;
  engine?: {
    type?: "aimax" | "claude-code" | "codex" | "opencode" | "pi" | "acp" | null;
    runtimeAgent?: "aimax" | "claude-code" | "codex" | "opencode" | "pi" | "acp" | null;
    runtimeConfig?: UniRuntimeConfig;
  } | null;
};

engine.type and the existing engine.runtimeAgent field are compatible engine-type inputs. A missing or null engine, an empty engine object, or a missing, null, blank, or whitespace-only selection defaults to aimax. If one compatibility field is empty and the other contains a supported value, the supported value is used. When both contain non-empty values they must match. aimax selects the existing CLI/agents path; all other supported values select the corresponding Uni runtime. Unknown types and aliases such as claudecode are rejected before the one-shot request is accepted.

/run without engine, or with aimax

POST /run accepts the same run options as aimax run under run, using the CLI RunOptions camelCase field names. For example, --session-id becomes sessionId, --resume-request-id becomes resumeRequestId, and --resume-input-json becomes resumeInputJson. Model sampling flags are also passed this way: --temperature, --top-k, and --top-p become temperature, topK, and topP.

When a valid run is accepted, the server responds immediately with HTTP 202. The response only acknowledges that the one-shot run was accepted; task progress and completion still use the configured CLI stdout, callback, or websocket channels.

{
  "status": "running",
  "accepted": true,
  "receivedAt": "2026-07-02 16:00:00.000",
  "respondedAt": "2026-07-02 16:00:00.012"
}

receivedAt is the server-side time when /run handling started. respondedAt is the server-side time immediately before the HTTP acceptance response is written. Both fields use the same China local timestamp format as CLI logs: YYYY-MM-DD HH:mm:ss.SSS.

For structured message input, pass run.messages instead of encoding JSON into run.message:

{
  "run": {
    "dataDir": "/data/user1",
    "temperature": "0.2",
    "topK": "40",
    "topP": "0.9",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "/new" },
          { "type": "image", "data": "<base64>", "mimeType": "image/png" }
        ]
      }
    ]
  }
}

run.messages uses the same structured Message format as aimax run --from-file. run.message remains plain user text and is not JSON-parsed by the server.

Resume-related run options are also forwarded through the same CLI path:

{
  "run": {
    "dataDir": "/data/user1",
    "sessionId": "sess-001",
    "resumeRequestId": "hitl-001",
    "resumeInputJson": "{\"action\":\"submit\",\"values\":{\"approved\":true}}"
  }
}

resumeInputJson is the canonical field. For compatibility with older server-mode callers, run.resumeRequestJson is also accepted and normalized to run.resumeInputJson when the canonical field is not provided.

/run with a Uni engine

Use engine when the container should run via @gencode/uni instead of the legacy agents/CLI path:

{
  "env": {
    "AIMAX_DATA_DIR": "/data/user1",
    "OPENAI_API_KEY": "sk-xxx"
  },
  "run": {
    "projectDir": "/data/user1/workspace/repo",
    "message": "hello",
    "output": "json"
  },
  "engine": {
    "type": "codex",
    "runtimeConfig": {
      "command": "codex",
      "args": ["exec"]
    }
  }
}

Top-level env still applies during execution. Unsupported uni fields present in run (for example pluginsConfig, agent, resume fields) are removed before executeUniRun(); they do not cause a 400 response.

For engine.type = "codex", run.messages may contain one structured Message object or a non-empty Message array. Exactly one of run.message, run.fromFile, or run.messages must be present. Codex resolves its CodeProxy API key from run.apiKey, then env.AIMAX_API_KEY, then env.AIMAX_LLM_API_KEY; it does not derive model authentication from run.authToken. A Codex request may provide absolute directories through run.skillsLoadPaths; on every real run or Resume, Uni combines them with /aimax/skills and <dataDir>/.aimax/skills, then links discovered Skill directories into the effective CODEX_HOME/skills before starting Codex.

To select the existing AIMax CLI/agents path explicitly, use:

{
  "run": {
    "dataDir": "/data/user1",
    "message": "hello"
  },
  "engine": {
    "type": "aimax"
  }
}