Agents

Create Agent

POST/v2/agents

Request Body

titlestringrequired

instructionsstringoptional

Harness that executes the agent's turns.

machine_kindstring · daytona | e2boptional

Sandbox provider the agent's machines run on. Omit to use the deployment default. Fixed at creation — updates cannot change it.

mcp_serversarray<object>optional

MCP server entries. Omit or null for none.

skillsarray<object>optional

Skill declarations. Omit or null for none.

secretsobjectoptional

Agent secrets, planted into every sandbox env as plain env vars. Backed by the brainbase platform — same store the CLI syncs via `brainbase agent pull`. Omit or null for none.

descriptionstringoptional

Optional freeform description, stored on the agent row.

metadataobjectoptional

Freeform string→string labels stored on the agent. Filter the list endpoint with repeated ?metadata=key:value params. Omit or null for none.

default_modelstringoptional

Default model id, stored in kafka_profiles.preferences.default_model (what the kafka-v2 client reads as the agent's model). Overrides a template's source_model when both are set.

shared_folder_enabledbooleanoptional

When true, future cloud-runtime task sandboxes mount this agent's shared folder at /workspace/Shared.

group_idstring · uuidoptional

If set, the new agent is also granted to this group via agent_group_access — making it visible to every member of the group. Caller must already be a member of the group.

template_slugstringoptional

Instantiate from an agent template, given as "creator/slug" (e.g. "acme/resume-reviewer-agent"). The template supplies instructions, runtime, model, mcp_servers and skills; the caller still provides title, group_id, and secret VALUES (the template only declares secret placeholders). Fields set explicitly on this body override the template. There is no separate instantiate endpoint — this is the one creation path.

entrypointstringoptional

Bash snippet executed inside the sandbox after env vars are loaded and `brainbase agent pull` completes, before the in-VM runner is launched. Use it to clone a side repo, install dependencies the harness needs, or set up local state. Runs as the sandbox user with cwd=/workspace; stdout/stderr go to /workspace/.brainbase/entrypoint.log. Failures are logged but do not block the agent from coming up. Omit or null for none.

Request

curl --request POST \
  --url https://api.brainbaselabs.com/v2/agents \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "title": "string",
  "instructions": "",
  "runtime_kind": "claude_code",
  "machine_kind": "daytona",
  "mcp_servers": [
    {
      "name": "string",
      "url": "string",
      "command": "string",
      "args": [
        "string"
      ],
      "env": {
        "property1": "string",
        "property2": "string"
      },
      "headers": {
        "property1": "string",
        "property2": "string"
      },
      "is_enabled": true
    }
  ],
  "skills": [
    {
      "source": "string"
    }
  ],
  "secrets": {
    "property1": "string",
    "property2": "string"
  },
  "description": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "default_model": "string",
  "shared_folder_enabled": false,
  "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
  "template_slug": "string",
  "entrypoint": "string"
}'

Response

json

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "owner_user_id": "65139110-7c3c-4777-b692-80c218be3b9d",
  "title": "string",
  "instructions": "string",
  "runtime_kind": "string",
  "machine_kind": "string",
  "default_model": "string",
  "mcp_servers": [
    {
      "name": "string",
      "url": "string",
      "command": "string",
      "args": [
        "string"
      ],
      "env": {
        "property1": "string",
        "property2": "string"
      },
      "headers": {
        "property1": "string",
        "property2": "string"
      },
      "is_enabled": true
    }
  ],
  "skills": [
    {
      "source": "string"
    }
  ],
  "secrets": {
    "property1": "string",
    "property2": "string"
  },
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "shared_folder_enabled": false,
  "entrypoint": "",
  "created_at": "2019-08-24T14:15:22Z"
}