---
title: "Launch Workspace Session"
method: POST
path: "/api/v1/workspaces/{workspace_id}/sessions"
tags: ["workspaces"]
---

# Launch Workspace Session

`POST /api/v1/workspaces/{workspace_id}/sessions`

Launch a daemon-backed coding session for the given workspace.

## Path parameters

- `workspace_id` string, required

## Request body

- WorkspaceSessionLaunchRequest — Request body used to start a session for a workspace.
  - `machine_id` string, nullable — Machine ID to launch the session on. If not provided, uses the workspace's default machine.
  - `user_session_id` string, nullable — Existing user session to reuse
  - `metadata` object, nullable — Arbitrary metadata describing the launch
  - `initial_prompt` string, nullable — Prompt delivered to the coding agent at startup
  - `worktree_name` string, nullable — Name for the git worktree/branch to use for this session
  - `session_settings` SessionSettingsInput — Per-session settings for a user session.
    - `code` CodeAgentSettingsInput — Settings for the code agent across providers.
      - `mode` 'agent' | 'orchestrator', nullable
      - `default_provider` string, nullable
      - `providers` CodeAgentProviders — Provider-specific code agent settings keyed by provider name.
        - `claude_code` ClaudeCodeSettings — Claude-specific settings for the code agent.
          - `model` 'haiku' | 'sonnet' | 'opus' | 'opus[1m]', nullable
        - `codex` CodexSettings — Codex-specific settings for the code agent.
          - `model` 'gpt-5.1-codex-max' | 'gpt-5.1-codex-mini' | 'gpt-5.1-codex' | 'gpt-5.2' | 'gpt-5.2-codex' | 'gpt-5.3-codex-spark' | 'gpt-5.3-codex', nullable
          - `thinking` 'low' | 'medium' | 'high' | 'xhigh', nullable
    - `voice` VoiceAgentSettings — Settings for the voice agent.
      - `language` string, nullable
  - `resume_session_id` string, nullable — SDK session ID to resume from (e.g., from Claude CLI import)
  - `agent_session_id` string, nullable — Existing agent session ID to connect to (e.g., from import)

## Response `201`

Successful Response

- WorkspaceSessionLaunchResponse — Daemon acknowledgement returned after a launch request.
  - `status` string, required — Launch status (e.g., 'ok', 'error')
  - `payload` object, nullable — Optional response payload with additional details

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/omnara/apis/omnara-api.md) · [All operations](https://skmtc.dev/omnara/apis/omnara-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/omnara/omnara-api/revisions/624048e40cad/schema)