---
title: "Start a plugin session [write]"
method: POST
path: "/plugins/{name}/sessions"
---

# Start a plugin session \[write\]

`POST /plugins/{name}/sessions`

## Request

- Base URL: `https://api.agentsky.dev/v1`
- URL: `https://api.agentsky.dev/v1/plugins/{name}/sessions`
- Auth: HTTP bearer

RFC-0155 §3. The session starts with only the plugin's skills (not the workspace's default skills) and its remote MCP servers, and its calls to connected apps are limited to the apps the plugin declared: any other app is refused (capability_denied, reason plugin_scope). agent defaults to the workspace's Sky. Answers the created session.

## Path parameters

- `name` string, required

## Request body

- object
  - `message` string, required
  - `agent` string
  - `title` string

## Response `201`

Created

- Session
  - `id` string: sess_… identifier
  - `agentId` string, nullable: The agent id (agent_…)
  - `title` string, nullable
  - `status` 'provisioning' | 'idle' | 'running' | 'terminated': provisioning = the sandbox is booting or installing the environment's packages (a turn sent meanwhile waits for it); running = a turn is in flight; terminated = archived or the last runtime was destroyed. Use archived for the durable archive receipt
  - `provisioningStage` 'creating_computer' | 'starting_agent' | 'null', nullable: Which part of its boot the session's computer is in, as the platform observed it: creating_computer until the sandbox provider reports the computer exists, then starting_agent until the agent in it answers. A provider that does not report the computer's creation stays at creating_computer. Null once the computer is up and whenever it is not booting.
  - `archived` boolean: True only after this Session's archive mark was durably written; false for an active Session whose runtime was destroyed
  - `agentType` string
  - `llm` string: The model this session runs on (PATCH to change; the agent's model is unchanged)
  - `harnessVersion` string: Harness release the session runs: the one its serving pod booted, the restored checkpoint's for a native-fork handoff, the agent's pin for ACP harnesses, otherwise the current release
  - `reasoningEffort` string, nullable: The model-compatible effort resolved from the session pin, then agent pin. Constrained models use an allowed fallback; no-setting models return null. Unpinned unconstrained models return null for the harness default.
  - `subscriptionApiFallback` boolean: Opt-in to paid API continuation after all subscription accounts exhaust, preserving the same supported explicit model and wallet/budget gates
  - `modelBilling` 'platform' | 'account': Who pays for model calls: platform wallet or the user's connected subscription
  - `idleTimeoutSeconds` integer, nullable: Seconds the session's machine stays awake after a turn ends before it is paused; null = the platform default of 60. Set it when people use apps on the session's exposed ports after the agent finishes
  - `browserProfile` string: Resolved browser: the session's choice, then the agent's default, then mine. mine is the browser of the person whose turn it is; fresh is signed out; user:<user id> is the sites that person shared with whoever runs the turn. Applied before the next browser turn when browser profiles are enabled.
  - `browserLoginsSavedAt` string, date-time, nullable: Most recent browser login save-back time, or null when this session has not saved changed logins.
  - `default` boolean: Is this the agent's default session
  - `payer` object: Who pays for it, decided once when it was created and never changed. Present only when a payer was recorded, which happens in a team workspace where workspace wallets are on; absent means its owner's own balance pays.
    - `type` 'workspace' | 'personal', required: `workspace`: the team workspace's own wallet. `personal`: the balance of the person who started it.
    - `workspace` object: The paying workspace; only with type workspace
      - `slug` string
      - `name` string
  - `metadata` object
  - `budget` object, nullable: Hard spend cap, or null when the session has none. A reached budget pauses the session (402 budget_reached on new work) until the cap is raised above consumed_cost or removed — removal is one-way.
    - `max_list_cost` MonetaryAmount: A US-dollar amount. `amount` is whole US cents as an integer decimal string — "125" is $1.25 — rounded half-up to the cent.
      - `amount` string, required: Whole US cents
      - `currency` 'USD', required
      - `unit` 'cents': The unit of `amount`; present on every amount the API returns
      - `amount_usd` string: The exact amount in US dollars, up to six decimals — "0.0038" for spend that rounds to 0 cents. Returned, never accepted.
    - `consumed_cost` MonetaryAmount: A US-dollar amount. `amount` is whole US cents as an integer decimal string — "125" is $1.25 — rounded half-up to the cent.
      - `amount` string, required: Whole US cents
      - `currency` 'USD', required
      - `unit` 'cents': The unit of `amount`; present on every amount the API returns
      - `amount_usd` string: The exact amount in US dollars, up to six decimals — "0.0038" for spend that rounds to 0 cents. Returned, never accepted.
    - `reached` boolean
    - `reached_at` string, nullable: ISO 8601
  - `parentSessionId` string, nullable: The session this one came from: a helper names the session that hired it, a handoff child names the session it continued; null for a root. Every session a task's root produced, with its role, is GET /tasks/{id}?by=session on any member's id.
  - `parentRelation` 'helper' | 'handoff' | 'null', nullable: How this session relates to parentSessionId: `helper` was hired by it (actl hire or the orchestration API), `handoff` continued its conversation on another agent; null for a root.
  - `resources` SessionResource[]: The files, GitHub repositories, and read-only memory stores mounted into the session, oldest first
    - union: A file, GitHub repository, or memory-store snapshot mounted read-only into the session. A read_write memory-store grant also permits updates through the session-scoped Agent API. Workspace paths are under /workspace; memory paths are under /mnt/memory. A file resource's `file_id` is the per-session copy (listed under GET /files?scope_id=). Repository tokens and memory contents are never echoed here.
      - object
        - `type` 'file', required
        - `id` string, required: sesrsc_…
        - `file_id` string, required: The per-session copy (file_…), read-only at mount_path
        - `mount_path` string, required: Absolute, under /workspace
        - `created_at` string, date-time, required
        - `updated_at` string, date-time, required
      - object
        - `type` 'github_repository', required
        - `id` string, required: sesrsc_…
        - `url` string, required: https://github.com/{owner}/{repo}
        - `mount_path` string, required: Absolute, under /workspace; the clone's root
        - `checkout` object: {type:"branch", name} or {type:"commit", sha}; absent = the default branch
          - `type` 'branch' | 'commit'
          - `name` string
          - `sha` string
        - `created_at` string, date-time, required
        - `updated_at` string, date-time, required
      - object
        - `type` 'memory_store', required
        - `id` string, required: smsr_…
        - `memory_store_id` string, required: memstore_…
        - `mount_path` string, required: Absolute, under /mnt/memory
        - `access` 'read_only' | 'read_write', required
        - `instructions` string: Optional per-session guidance
        - `created_at` string, date-time, required
        - `updated_at` string, date-time, required
  - `workspaceDefaults` object, nullable: What the session started with because its workspace made it a default; everything else it carries was named at creation. Null when it took nothing.
    - `environmentId` string, nullable, required: The workspace's default environment, when the session named none
    - `vaultIds` string[], required: The workspace's default vault, when it holds a secret
    - `mountPaths` string[], required: Where each always-available file was mounted
    - `skillIds` string[], required: The always-available skills
  - `contextFiles` object, nullable: The workspace files the session loaded into its instructions when its sandbox was last provisioned (GET /workspace-context describes the set); null before that and for a session without its workspace's store. Every other file in the store is read on demand.
    - `memoryStoreId` string, required
    - `mountPath` string, required
    - `memberHandle` string, nullable, required: Whose members/ page was loaded: the person who started the session
    - `loadedAt` string, required: ISO 8601
    - `files` object[], required
      - `path` string, required
      - `bytes` integer, required: UTF-8 bytes of the whole file
      - `loadedChars` integer, required: Characters of it the session loaded
      - `truncated` boolean, required
    - `missing` string[], required: Always-loaded paths the workspace has not written yet
  - `hostedBySeller` object: Present only when the session runs on its agent's maker's own server instead of a sandbox: what is sent to the session goes to this host. `agentType` and `llm` then name a stand-in that never runs.
    - `host` string, required
  - `attachments` object[]: Everything the session started with: its environment, vaults, mounted files and memory stores, and the workspace's always-available skills. The skills of the session's agent are on the agent and are not repeated here.
    - `type` 'environment' | 'vault' | 'file' | 'skill' | 'memory_store', required
    - `id` string, required: The id of the environment, vault, file, skill or memory store
    - `mountPath` string, nullable, required: Where a file or memory store is mounted; null for the other types
    - `source` 'default' | 'explicit', required: default = the workspace supplied it; explicit = it was named when the session was created. A memory store on a session created before 2026-10-06 reads as explicit
  - `createdAt` string: ISO 8601

## Other responses

- `default`: Error — { error: { code, message, request_id } }

## Changes

- **2026-11-02** `e5e8f0229a99`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/plugins/:name/sessions/post.md)

---

[API](https://skmtc.dev/agentsky/apis/agentsky-developer-api.md) - [All operations](https://skmtc.dev/agentsky/apis/agentsky-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentsky/apis/agentsky-developer-api/revisions/8280a065ef6a?raw)