version: "1.0.3" name: session-control description: Start and stop agentic sessions in sgai workspaces. Use when you need to launch AI agent sessions or halt running sessions. compatibility: Requires a running sgai server with workspaces that have a GOAL.md configured.

Session Control

Sessions are the running instances of AI agents working on a workspace. Each workspace can have at most one running session.

Start a Session

Endpoint: POST /api/v1/workspaces/{name}/start

# Brainstorming mode (interactive, pauses for human input)
curl -X POST $BASE_URL/api/v1/workspaces/my-project/start \
  -H "Content-Type: application/json" \
  -d '{"auto": false}'
 
# Self-drive mode (fully autonomous, no pausing)
curl -X POST $BASE_URL/api/v1/workspaces/my-project/start \
  -H "Content-Type: application/json" \
  -d '{"auto": true}'

Request:

{"auto": true}

Response:

{
  "name": "my-project",
  "status": "running",
  "running": true,
  "message": "session started"
}

Session Modes

Notes:

• Root workspaces cannot start agentic work (only forks/standalone can)
• If already running, returns "message": "session already running"

Stop a Session

Endpoint: POST /api/v1/workspaces/{name}/stop

curl -X POST $BASE_URL/api/v1/workspaces/my-project/stop

Response:

{
  "name": "my-project",
  "status": "stopped",
  "running": false,
  "message": "session stopped"
}

If already stopped: "message": "session already stopped"

Check Running Status

Use the full state endpoint to check session status:

STATE=$(curl -s $BASE_URL/api/v1/state)
RUNNING=$(echo $STATE | jq '.workspaces[] | select(.name=="my-project") | .running')
TASK=$(echo $STATE | jq -r '.workspaces[] | select(.name=="my-project") | .task')

Key workspace state fields for session monitoring:

Open in OpenCode (Local Only)

Open the workspace in OpenCode terminal (localhost connections only).

Endpoint: POST /api/v1/workspaces/{name}/open-opencode

curl -X POST http://localhost:PORT/api/v1/workspaces/my-project/open-opencode

Response:

{
  "opened": true,
  "message": "opened in opencode"
}

Errors:

• 403 — remote connections not allowed (localhost only)
• 409 — session not running

Open in Editor

Open the workspace directory in the configured editor (VS Code, etc.).

Endpoint: POST /api/v1/workspaces/{name}/open-editor

curl -X POST $BASE_URL/api/v1/workspaces/my-project/open-editor

Response:

{
  "opened": true,
  "editor": "code",
  "message": "opened in editor"
}

Open Specific Files

# Open GOAL.md in editor
curl -X POST $BASE_URL/api/v1/workspaces/my-project/open-editor/goal
 
# Open PROJECT_MANAGEMENT.md in editor
curl -X POST $BASE_URL/api/v1/workspaces/my-project/open-editor/project-management