server

package
v0.64.12 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 22, 2026 License: MIT Imports: 43 Imported by: 0

Documentation

Overview

Package server hosts agentserver's HTTP API. The swag-style comments in this file declare the OpenAPI document metadata; per-route annotations live on individual handler funcs. 

@title          agentserver API
@version        0.1.0
@description    Public REST API for agentserver. Generated from
@description    Go handler annotations via swaggo/swag; see
@description    docs/api/README.md for regeneration instructions.
@BasePath       /
@securityDefinitions.apikey  CookieAuth
@in                          cookie
@name                        agentserver-token
@description                 Session cookie set by POST /api/auth/login. All non-auth endpoints assume this cookie.

Index

Constants

View Source 
const ScopeTurnsSubmit = "turns:submit"

ScopeTurnsSubmit is the constant used by /api/turns to assert presence. Each enforcement site declares its own constant to make grep easy.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIKeyScope added in v0.64.12 

type APIKeyScope struct {
	Name        string
	Description string
	Available   bool // false = listed in catalog but not yet enforced anywhere; mint rejects it
}

APIKeyScope is one entry in the workspace API key scope catalog. The catalog lives in code (not the DB) because adding/changing scopes requires handler-side enforcement changes anyway — keeping them in lockstep with code avoids migration drift.

Naming convention: "<resource>:<verb>". Match this 1:1 with the swag operationId of the handler that enforces it.

type APIKeyScopeDescriptor added in v0.64.12 

type APIKeyScopeDescriptor struct {
	Name        string `json:"name" validate:"required" example:"turns:submit"`
	Description string `json:"description" validate:"required"`
	Available   bool   `json:"available" validate:"required"`

} // @name APIKeyScopeDescriptor

APIKeyScopeDescriptor is one entry in the scope catalog returned by GET /api/workspaces/{wid}/api-keys/scopes. The SPA renders these as checkboxes in the mint modal.

type AdminOwnerInfo added in v0.64.5 

type AdminOwnerInfo struct {
	ID      string  `json:"id" validate:"required"`
	Email   string  `json:"email" validate:"required"`
	Name    *string `json:"name" extensions:"x-nullable=true"`
	Picture *string `json:"picture" extensions:"x-nullable=true"`

} // @name AdminOwnerInfo

AdminOwnerInfo is the owner summary embedded in AdminWorkspaceItem.

type AdminQuotaDefaultsResponse added in v0.64.5 

type AdminQuotaDefaultsResponse struct {
	MaxWorkspacesPerUser     int   `json:"max_workspaces_per_user" validate:"required"`
	MaxSandboxesPerWorkspace int   `json:"max_sandboxes_per_workspace" validate:"required"`
	MaxWorkspaceDriveSize    int64 `json:"max_workspace_drive_size" validate:"required"`
	MaxSandboxCPU            int   `json:"max_sandbox_cpu" validate:"required"`
	MaxSandboxMemory         int64 `json:"max_sandbox_memory" validate:"required"`
	MaxIdleTimeout           int   `json:"max_idle_timeout" validate:"required"`
	WsMaxTotalCPU            int   `json:"ws_max_total_cpu" validate:"required"`
	WsMaxTotalMemory         int64 `json:"ws_max_total_memory" validate:"required"`
	WsMaxIdleTimeout         int   `json:"ws_max_idle_timeout" validate:"required"`

} // @name AdminQuotaDefaultsResponse

AdminQuotaDefaultsResponse is returned by GET /api/admin/quotas/defaults and PUT /api/admin/quotas/defaults.

type AdminQuotaDefaultsUpdateRequest added in v0.64.5 

type AdminQuotaDefaultsUpdateRequest struct {
	MaxWorkspacesPerUser     *int   `json:"max_workspaces_per_user,omitempty"`
	MaxSandboxesPerWorkspace *int   `json:"max_sandboxes_per_workspace,omitempty"`
	MaxWorkspaceDriveSize    *int64 `json:"max_workspace_drive_size,omitempty"`
	MaxSandboxCPU            *int   `json:"max_sandbox_cpu,omitempty"`
	MaxSandboxMemory         *int64 `json:"max_sandbox_memory,omitempty"`
	MaxIdleTimeout           *int   `json:"max_idle_timeout,omitempty"`
	WsMaxTotalCPU            *int   `json:"ws_max_total_cpu,omitempty"`
	WsMaxTotalMemory         *int64 `json:"ws_max_total_memory,omitempty"`
	WsMaxIdleTimeout         *int   `json:"ws_max_idle_timeout,omitempty"`

} // @name AdminQuotaDefaultsUpdateRequest

AdminQuotaDefaultsUpdateRequest is the body for PUT /api/admin/quotas/defaults. All fields are optional; only supplied keys are applied.

type AdminSandboxItem added in v0.64.5 

type AdminSandboxItem struct {
	ID             string  `json:"id" validate:"required"`
	Name           string  `json:"name" validate:"required"`
	WorkspaceID    string  `json:"workspace_id" validate:"required"`
	Type           string  `json:"type" validate:"required" example:"opencode"`
	Status         string  `json:"status" validate:"required" example:"running"`
	CreatedAt      string  `json:"created_at" validate:"required"`
	LastActivityAt *string `json:"last_activity_at,omitempty" extensions:"x-nullable=true"`
	IsLocal        bool    `json:"is_local"`

} // @name AdminSandboxItem

AdminSandboxItem is one entry returned by GET /api/admin/sandboxes.

type AdminSetUserQuotaRequest added in v0.64.5 

type AdminSetUserQuotaRequest struct {
	MaxWorkspaces *int `json:"max_workspaces" extensions:"x-nullable=true"`

} // @name AdminSetUserQuotaRequest

AdminSetUserQuotaRequest is the body for PUT /api/admin/users/{id}/quota.

type AdminSetWorkspaceQuotaRequest added in v0.64.5 

type AdminSetWorkspaceQuotaRequest struct {
	MaxSandboxes     *int   `json:"max_sandboxes,omitempty" extensions:"x-nullable=true"`
	MaxSandboxCPU    *int   `json:"max_sandbox_cpu,omitempty" extensions:"x-nullable=true"`
	MaxSandboxMemory *int64 `json:"max_sandbox_memory,omitempty" extensions:"x-nullable=true"`
	MaxIdleTimeout   *int   `json:"max_idle_timeout,omitempty" extensions:"x-nullable=true"`
	MaxTotalCPU      *int   `json:"max_total_cpu,omitempty" extensions:"x-nullable=true"`
	MaxTotalMemory   *int64 `json:"max_total_memory,omitempty" extensions:"x-nullable=true"`
	MaxDriveSize     *int64 `json:"max_drive_size,omitempty" extensions:"x-nullable=true"`

} // @name AdminSetWorkspaceQuotaRequest

AdminSetWorkspaceQuotaRequest is the body for PUT /api/admin/workspaces/{id}/quota. All fields are optional; only supplied keys are applied (merged with existing).

type AdminUpdateUserRoleRequest added in v0.64.5 

type AdminUpdateUserRoleRequest struct {
	Role string `json:"role" validate:"required" example:"admin"`

} // @name AdminUpdateUserRoleRequest

AdminUpdateUserRoleRequest is the body for PUT /api/admin/users/{id}/role.

type AdminUserItem added in v0.64.5 

type AdminUserItem struct {
	ID        string  `json:"id" validate:"required"`
	Email     string  `json:"email" validate:"required"`
	Name      *string `json:"name" extensions:"x-nullable=true"`
	Role      string  `json:"role" validate:"required" example:"user"`
	CreatedAt string  `json:"created_at" validate:"required"`

} // @name AdminUserItem

AdminUserItem is one entry returned by GET /api/admin/users.

type AdminUserQuotaDefaults added in v0.64.5 

type AdminUserQuotaDefaults struct {
	MaxWorkspacesPerUser int `json:"max_workspaces_per_user" validate:"required"`

} // @name AdminUserQuotaDefaults

AdminUserQuotaDefaults is the system-default quota sub-object embedded in AdminUserQuotaResponse.

type AdminUserQuotaOverrides added in v0.64.5 

type AdminUserQuotaOverrides struct {
	MaxWorkspaces *int   `json:"max_workspaces" extensions:"x-nullable=true"`
	UpdatedAt     string `json:"updated_at" validate:"required"`

} // @name AdminUserQuotaOverrides

AdminUserQuotaOverrides is the per-user override sub-object embedded in AdminUserQuotaResponse. null when no override is set.

type AdminUserQuotaResponse added in v0.64.5 

type AdminUserQuotaResponse struct {
	Defaults  AdminUserQuotaDefaults   `json:"defaults" validate:"required"`
	Overrides *AdminUserQuotaOverrides `json:"overrides" extensions:"x-nullable=true"`

} // @name AdminUserQuotaResponse

AdminUserQuotaResponse is returned by GET /api/admin/users/{id}/quota.

type AdminWorkspaceItem added in v0.64.5 

type AdminWorkspaceItem struct {
	ID           string          `json:"id" validate:"required"`
	Name         string          `json:"name" validate:"required"`
	CreatedAt    string          `json:"created_at" validate:"required"`
	UpdatedAt    string          `json:"updated_at" validate:"required"`
	Owner        *AdminOwnerInfo `json:"owner" extensions:"x-nullable=true"`
	SandboxCount int             `json:"sandbox_count"`
	MaxSandboxes int             `json:"max_sandboxes"`

} // @name AdminWorkspaceItem

AdminWorkspaceItem is one entry returned by GET /api/admin/workspaces.

type AdminWorkspaceQuotaDefaults added in v0.64.5 

type AdminWorkspaceQuotaDefaults struct {
	MaxSandboxes     int   `json:"max_sandboxes" validate:"required"`
	MaxSandboxCPU    int   `json:"max_sandbox_cpu" validate:"required"`
	MaxSandboxMemory int64 `json:"max_sandbox_memory" validate:"required"`
	MaxIdleTimeout   int   `json:"max_idle_timeout" validate:"required"`
	MaxTotalCPU      int   `json:"max_total_cpu" validate:"required"`
	MaxTotalMemory   int64 `json:"max_total_memory" validate:"required"`
	MaxDriveSize     int64 `json:"max_drive_size" validate:"required"`

} // @name AdminWorkspaceQuotaDefaults

AdminWorkspaceQuotaDefaults is the system-default quota sub-object embedded in AdminWorkspaceQuotaResponse.

type AdminWorkspaceQuotaOverrides added in v0.64.5 

type AdminWorkspaceQuotaOverrides struct {
	MaxSandboxes     *int   `json:"max_sandboxes" extensions:"x-nullable=true"`
	MaxSandboxCPU    *int   `json:"max_sandbox_cpu" extensions:"x-nullable=true"`
	MaxSandboxMemory *int64 `json:"max_sandbox_memory" extensions:"x-nullable=true"`
	MaxIdleTimeout   *int   `json:"max_idle_timeout" extensions:"x-nullable=true"`
	MaxTotalCPU      *int   `json:"max_total_cpu" extensions:"x-nullable=true"`
	MaxTotalMemory   *int64 `json:"max_total_memory" extensions:"x-nullable=true"`
	MaxDriveSize     *int64 `json:"max_drive_size" extensions:"x-nullable=true"`
	UpdatedAt        string `json:"updated_at" validate:"required"`

} // @name AdminWorkspaceQuotaOverrides

AdminWorkspaceQuotaOverrides is the per-workspace override sub-object embedded in AdminWorkspaceQuotaResponse. null when no override is set.

type AdminWorkspaceQuotaResponse added in v0.64.5 

type AdminWorkspaceQuotaResponse struct {
	Defaults  AdminWorkspaceQuotaDefaults   `json:"defaults" validate:"required"`
	Overrides *AdminWorkspaceQuotaOverrides `json:"overrides" extensions:"x-nullable=true"`

} // @name AdminWorkspaceQuotaResponse

AdminWorkspaceQuotaResponse is returned by GET /api/admin/workspaces/{id}/quota.

type AgentCardItem added in v0.64.5 

type AgentCardItem struct {
	AgentID     string      `json:"agent_id" validate:"required"`
	DisplayName string      `json:"display_name" validate:"required"`
	Description string      `json:"description"`
	AgentType   string      `json:"agent_type" validate:"required" example:"claudecode"`
	Status      string      `json:"status" validate:"required" example:"available"`
	Card        interface{} `json:"card" validate:"required"`
	Version     int         `json:"version" validate:"required"`

} // @name AgentCardItem

AgentCardItem is one entry in the agent card list returned by GET /api/workspaces/{wid}/agents and GET /api/agent/discovery/agents. card is the raw capability descriptor JSON submitted at registration time.

type AgentCardRegisterRequest added in v0.64.5 

type AgentCardRegisterRequest struct {
	DisplayName string      `json:"display_name" example:"My Agent"`
	Description string      `json:"description" example:"A helpful coding agent"`
	AgentType   string      `json:"agent_type" example:"claudecode"` // optional; defaults to "claudecode"
	Card        interface{} `json:"card"`                            // optional; arbitrary JSON

} // @name AgentCardRegisterRequest

AgentCardRegisterRequest is the body for POST /api/agent/discovery/cards. card is an arbitrary JSON capability descriptor; defaults to {} when omitted.

type AgentCardRegisterResponse added in v0.64.5 

type AgentCardRegisterResponse struct {
	Status string `json:"status" validate:"required" example:"ok"`

} // @name AgentCardRegisterResponse

AgentCardRegisterResponse is the {"status":"ok"} body returned (200) by POST /api/agent/discovery/cards.

type AgentHealthMonitor added in v0.30.0 

type AgentHealthMonitor struct {
	// contains filtered or unexported fields
}

AgentHealthMonitor periodically marks stale agents as offline.

func NewAgentHealthMonitor added in v0.30.0 

func NewAgentHealthMonitor(database *db.DB) *AgentHealthMonitor

func (*AgentHealthMonitor) Run added in v0.30.0 

func (m *AgentHealthMonitor) Run(ctx context.Context)

Run blocks until ctx is cancelled.

type AgentInteractionItem added in v0.64.5 

type AgentInteractionItem struct {
	ID         int64       `json:"id" validate:"required"`
	ActorID    *string     `json:"actor_id" extensions:"x-nullable=true"`
	Action     string      `json:"action" validate:"required" example:"task.created"`
	TargetID   string      `json:"target_id" validate:"required"`
	TargetType string      `json:"target_type" validate:"required" example:"task"`
	Detail     interface{} `json:"detail,omitempty"`
	CreatedAt  string      `json:"created_at" validate:"required"`

} // @name AgentInteractionItem

AgentInteractionItem is one entry in the audit trail returned by GET /api/workspaces/{wid}/agent-interactions. detail is an arbitrary JSON object; it is absent when empty.

type AgentMailboxMessage added in v0.64.5 

type AgentMailboxMessage struct {
	ID        string `json:"id" validate:"required"`
	From      string `json:"from" validate:"required"`
	Text      string `json:"text" validate:"required"`
	MsgType   string `json:"msg_type" validate:"required" example:"text"`
	CreatedAt string `json:"created_at" validate:"required"`

} // @name AgentMailboxMessage

AgentMailboxMessage is one message in the inbox returned by GET /api/agent/mailbox/inbox.

type AgentMailboxSendRequest added in v0.64.5 

type AgentMailboxSendRequest struct {
	To      string `json:"to" validate:"required" example:"sandbox-uuid-of-target"`
	Text    string `json:"text" validate:"required" example:"Hello from another agent"`
	MsgType string `json:"msg_type,omitempty" example:"text"`

} // @name AgentMailboxSendRequest

AgentMailboxSendRequest is the body for POST /api/agent/mailbox/send. msg_type defaults to "text" when omitted.

type AgentMailboxSendResponse added in v0.64.5 

type AgentMailboxSendResponse struct {
	MessageID string `json:"message_id" validate:"required"`
	Status    string `json:"status" validate:"required" example:"sent"`

} // @name AgentMailboxSendResponse

AgentMailboxSendResponse is returned (201) by POST /api/agent/mailbox/send.

type AgentRegisterRequest added in v0.64.5 

type AgentRegisterRequest struct {
	Name string `json:"name" example:"Local Agent"`
	Type string `json:"type" example:"opencode"` // optional; defaults to "opencode"

} // @name AgentRegisterRequest

AgentRegisterRequest is the body for POST /api/agent/register. type defaults to "opencode" when omitted; valid values: opencode, claudecode, custom.

type AgentRegisterResponse added in v0.64.5 

type AgentRegisterResponse struct {
	SandboxID   string `json:"sandbox_id" validate:"required"`
	TunnelToken string `json:"tunnel_token" validate:"required"`
	ProxyToken  string `json:"proxy_token" validate:"required"`
	WorkspaceID string `json:"workspace_id" validate:"required"`
	ShortID     string `json:"short_id" validate:"required"`

} // @name AgentRegisterResponse

AgentRegisterResponse is returned (201) by POST /api/agent/register. proxy_token is the Bearer token used for subsequent agent-facing API calls. tunnel_token is used by the tunnel transport (if applicable).

type AgentTaskCancelResponse added in v0.64.5 

type AgentTaskCancelResponse struct {
	Status string `json:"status" validate:"required" example:"cancelled"`

} // @name AgentTaskCancelResponse

AgentTaskCancelResponse is the {"status":"cancelled"} body returned (200) by POST /api/tasks/{id}/cancel.

type AgentTaskCreateRequest added in v0.64.5 

type AgentTaskCreateRequest struct {
	TargetID        string   `json:"target_id" validate:"required" example:"sandbox-uuid"`
	Prompt          string   `json:"prompt" validate:"required" example:"Run the test suite"`
	Skill           string   `json:"skill,omitempty" example:"testing"`
	SystemContext   string   `json:"system_context,omitempty"`
	MaxTurns        int      `json:"max_turns,omitempty" example:"50"`
	MaxBudgetUSD    float64  `json:"max_budget_usd,omitempty" example:"1.0"`
	TimeoutSeconds  int      `json:"timeout_seconds,omitempty" example:"300"`
	DelegationChain []string `json:"delegation_chain,omitempty"`
	RequesterID     string   `json:"requester_id,omitempty"`

} // @name AgentTaskCreateRequest

AgentTaskCreateRequest is the body for POST /api/workspaces/{wid}/tasks and POST /api/agent/tasks. timeout_seconds defaults to 300 when omitted.

type AgentTaskCreateResponse added in v0.64.5 

type AgentTaskCreateResponse struct {
	TaskID    string `json:"task_id" validate:"required"`
	SessionID string `json:"session_id"`
	Status    string `json:"status" validate:"required" example:"pending"`

} // @name AgentTaskCreateResponse

AgentTaskCreateResponse is returned (201) by the task creation endpoints. session_id is empty in the current implementation (bridge was removed).

type AgentTaskDetail added in v0.64.5 

type AgentTaskDetail struct {
	TaskID        string      `json:"task_id" validate:"required"`
	WorkspaceID   string      `json:"workspace_id" validate:"required"`
	RequesterID   string      `json:"requester_id"`
	TargetID      string      `json:"target_id" validate:"required"`
	Prompt        string      `json:"prompt" validate:"required"`
	Status        string      `json:"status" validate:"required" example:"pending"`
	NumTurns      int         `json:"num_turns"`
	CreatedAt     string      `json:"created_at" validate:"required"`
	SessionID     *string     `json:"session_id,omitempty" extensions:"x-nullable=true"`
	Skill         *string     `json:"skill,omitempty" extensions:"x-nullable=true"`
	TotalCostUSD  *float64    `json:"total_cost_usd,omitempty" extensions:"x-nullable=true"`
	Result        interface{} `json:"result,omitempty" extensions:"x-nullable=true"`
	FailureReason *string     `json:"failure_reason,omitempty" extensions:"x-nullable=true"`
	CompletedAt   *string     `json:"completed_at,omitempty" extensions:"x-nullable=true"`

} // @name AgentTaskDetail

AgentTaskDetail is the full task payload returned by GET /api/tasks/{id} and GET /api/agent/tasks/{id}. Optional fields are absent when not applicable.

type AgentTaskItem added in v0.64.5 

type AgentTaskItem struct {
	TaskID      string   `json:"task_id" validate:"required"`
	TargetID    string   `json:"target_id" validate:"required"`
	RequesterID string   `json:"requester_id"`
	Skill       string   `json:"skill,omitempty"`
	Status      string   `json:"status" validate:"required" example:"pending"`
	Prompt      string   `json:"prompt" validate:"required"`
	NumTurns    int      `json:"num_turns"`
	TotalCost   *float64 `json:"total_cost_usd,omitempty" extensions:"x-nullable=true"`
	CreatedAt   string   `json:"created_at" validate:"required"`
	CompletedAt *string  `json:"completed_at,omitempty" extensions:"x-nullable=true"`

} // @name AgentTaskItem

AgentTaskItem is one entry in the task list returned by GET /api/workspaces/{wid}/tasks. completed_at and total_cost_usd are null when not yet set.

type AgentTaskPollItem added in v0.64.5 

type AgentTaskPollItem struct {
	TaskID        string  `json:"task_id" validate:"required"`
	Prompt        string  `json:"prompt" validate:"required"`
	SystemContext string  `json:"system_context,omitempty"`
	MaxTurns      int     `json:"max_turns,omitempty"`
	MaxBudgetUSD  float64 `json:"max_budget_usd,omitempty"`
	SessionID     string  `json:"session_id,omitempty"`

} // @name AgentTaskPollItem

AgentTaskPollItem is one entry in the list returned by GET /api/agent/tasks/poll. Only the fields needed for immediate execution are included (no cost/status/audit fields).

type AgentTaskStatusRequest added in v0.64.5 

type AgentTaskStatusRequest struct {
	Status        string      `json:"status" validate:"required" example:"completed"`
	FailureReason string      `json:"failure_reason,omitempty"`
	Result        interface{} `json:"result,omitempty"`
	TotalCostUSD  *float64    `json:"total_cost_usd,omitempty" extensions:"x-nullable=true"`
	NumTurns      int         `json:"num_turns,omitempty"`

} // @name AgentTaskStatusRequest

AgentTaskStatusRequest is the body for PUT /api/agent/tasks/{id}/status. Valid status values: running, completed, failed, cancelled. failure_reason is required when status is "failed". result and total_cost_usd are used when status is "completed".

type AuthCredentials added in v0.64.5 

type AuthCredentials struct {
	Email    string `json:"email" example:"alice@example.com" validate:"required"`
	Password string `json:"password" example:"hunter2" validate:"required"`

} //@name AuthCredentials

AuthCredentials is the email+password body for POST /api/auth/login and POST /api/auth/register.

type AuthMeResponse added in v0.64.5 

type AuthMeResponse struct {
	ID      string  `json:"id" validate:"required"`
	Email   string  `json:"email" validate:"required"`
	Name    *string `json:"name" extensions:"x-nullable=true"`
	Picture *string `json:"picture" extensions:"x-nullable=true"`
	Role    string  `json:"role" example:"developer" validate:"required"`

} //@name AuthMeResponse

AuthMeResponse is the current user payload returned by GET /api/auth/me. Name and Picture are populated from OIDC profile data when present (login via password leaves both empty). Both fields are always present in the JSON response — nil pointers serialize as null (not omitted).

type AuthRegisterResponse added in v0.64.5 

type AuthRegisterResponse struct {
	ID    string `json:"id"    example:"7e7a4f6c-..." validate:"required"`
	Email string `json:"email" example:"alice@example.com" validate:"required"`

} //@name AuthRegisterResponse

AuthRegisterResponse is what POST /api/auth/register returns on success: the new user's id and the email it was registered with.

type AuthStatusResponse added in v0.64.5 

type AuthStatusResponse struct {
	Status string `json:"status" example:"ok" validate:"required"`

} //@name AuthStatusResponse

AuthStatusResponse is the {"status":"ok"} envelope returned by /api/auth/login, /api/auth/logout, and /api/auth/check on success.

type CodexBrowserItem added in v0.64.5 

type CodexBrowserItem struct {
	ID             string     `json:"id" validate:"required"`
	Name           string     `json:"name" validate:"required"`
	WorkspaceID    string     `json:"workspace_id" validate:"required"`
	CreatedAt      time.Time  `json:"created_at" validate:"required"`
	ExpiresAt      time.Time  `json:"expires_at" validate:"required"`
	IsOnline       bool       `json:"is_online" validate:"required"`
	LastUsedAt     *time.Time `json:"last_used_at,omitempty"`
	ClientIP       string     `json:"client_ip,omitempty"`
	ClientUA       string     `json:"client_ua,omitempty"`
	CodexVersion   string     `json:"codex_version,omitempty"`
	OS             string     `json:"os,omitempty"`
	ConnectedAt    *time.Time `json:"connected_at,omitempty"`
	DisconnectedAt *time.Time `json:"disconnected_at,omitempty"`

} // @name CodexBrowserItem

CodexBrowserItem is one entry returned by GET /api/workspaces/{wid}/browsers. It mirrors RemoteExecutor so DeviceListPanel can render both without per-type branches. is_online is true when at least one open browser session exists for the underlying codex token. All session fields come from the latest session row (open if any, otherwise the most recent historical row).

type CodexClient added in v0.60.14 

type CodexClient struct {
	// contains filtered or unexported fields
}

CodexClient calls codex-app-gateway's POST /api/turns.

func NewCodexClient added in v0.60.14 

func NewCodexClient(baseURL, internalSecret string) *CodexClient

func (*CodexClient) RunTurn added in v0.60.14 

func (c *CodexClient) RunTurn(ctx context.Context, req CodexTurnRequest) (*CodexTurnResponse, error)

type CodexTokenListItem added in v0.64.5 

type CodexTokenListItem struct {
	ID          string     `json:"id" validate:"required"`
	Name        string     `json:"name" validate:"required"`
	WorkspaceID string     `json:"workspace_id" validate:"required"`
	CreatedAt   time.Time  `json:"created_at" validate:"required"`
	ExpiresAt   time.Time  `json:"expires_at" validate:"required"`
	LastUsedAt  *time.Time `json:"last_used_at,omitempty" extensions:"x-nullable=true"`
	Revoked     bool       `json:"revoked"`
	RevokedAt   *time.Time `json:"revoked_at,omitempty" extensions:"x-nullable=true"`

} // @name CodexTokenListItem

CodexTokenListItem is one entry returned by GET /api/codex/tokens. The raw token value is never included. last_used_at and revoked_at are null when not applicable.

type CodexTokenMintRequest added in v0.64.5 

type CodexTokenMintRequest struct {
	WorkspaceID string `json:"workspace_id" validate:"required"`
	Name        string `json:"name" validate:"required" example:"my mac"`
	TTLDays     int    `json:"ttl_days,omitempty" example:"90"`

} // @name CodexTokenMintRequest

CodexTokenMintRequest is the body for POST /api/codex/tokens. ttl_days is optional; defaults to 90 (range: 1–365).

type CodexTokenMintResponse added in v0.64.5 

type CodexTokenMintResponse struct {
	ID          string    `json:"id" validate:"required"`
	Token       string    `json:"token" validate:"required"`
	Name        string    `json:"name" validate:"required"`
	WorkspaceID string    `json:"workspace_id" validate:"required"`
	ExpiresAt   time.Time `json:"expires_at" validate:"required"`
	CreatedAt   time.Time `json:"created_at" validate:"required"`

} // @name CodexTokenMintResponse

CodexTokenMintResponse is returned (201) by POST /api/codex/tokens. token is the full bearer value and is shown only once — store it securely.

type CodexTransportError added in v0.60.14 

type CodexTransportError struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

type CodexTurnRequest added in v0.60.14 

type CodexTurnRequest struct {
	WorkspaceID string          `json:"workspaceId"`
	ThreadID    *string         `json:"threadId,omitempty"`
	Params      json.RawMessage `json:"params"`
	TimeoutMs   int             `json:"timeoutMs,omitempty"`
}

CodexTurnRequest mirrors the spec'd /api/turns request body 1:1.

type CodexTurnResponse added in v0.60.14 

type CodexTurnResponse struct {
	ThreadID  string               `json:"threadId"`
	Turn      json.RawMessage      `json:"turn,omitempty"`
	Transport *CodexTransportError `json:"transport,omitempty"`
}

CodexTurnResponse mirrors the spec'd response.

type ConnectCommands added in v0.62.3 

type ConnectCommands struct {
	AgentIdentity string `json:"agent_identity"`
}

ConnectCommands is the Agent-Identity-only connect-command bundle returned by the Add Connector API. The pre-0.132 bcrypt path and the ChatGPT device-auth variant are gone — auth at /cloud/.../register now goes through the Agent Identity JWT (validated by agentserver), and the inbound ws verifies a short-lived HMAC ticket minted at register time.

type CredentialBindingCreateRequest added in v0.64.5 

type CredentialBindingCreateRequest struct {
	DisplayName string `json:"display_name" validate:"required" example:"My K8s Cluster"`
	Config      string `json:"config" validate:"required" example:"{\"server\": \"https://...\"}"`

} // @name CredentialBindingCreateRequest

CredentialBindingCreateRequest is the body for POST /api/workspaces/{id}/credentials/{kind}. config is a provider-specific JSON or YAML credential blob.

type CredentialBindingCreateResponse added in v0.64.5 

type CredentialBindingCreateResponse struct {
	ID              string `json:"id" validate:"required"`
	DisplayName     string `json:"display_name,omitempty"`
	ServerURL       string `json:"server_url,omitempty"`
	AuthType        string `json:"auth_type,omitempty"`
	IsDefault       bool   `json:"is_default"`
	Status          string `json:"status,omitempty" example:"pending_device_code"`
	VerificationURI string `json:"verification_uri,omitempty"`
	UserCode        string `json:"user_code,omitempty"`
	ExpiresIn       int    `json:"expires_in,omitempty"`

} // @name CredentialBindingCreateResponse

CredentialBindingCreateResponse is returned (201) by the create endpoint, or (202) when the provider initiates an OIDC device code flow. When status is "pending_device_code", verification_uri, user_code and expires_in are set; the caller must long-poll the device-complete endpoint.

type CredentialBindingItem added in v0.64.5 

type CredentialBindingItem struct {
	ID          string      `json:"id" validate:"required"`
	DisplayName string      `json:"display_name" validate:"required"`
	ServerURL   string      `json:"server_url"`
	AuthType    string      `json:"auth_type" validate:"required" example:"static"`
	PublicMeta  interface{} `json:"public_meta"`
	IsDefault   bool        `json:"is_default"`
	CreatedAt   string      `json:"created_at" validate:"required"`

} // @name CredentialBindingItem

CredentialBindingItem is one entry in the list returned by GET /api/workspaces/{id}/credentials/{kind}. public_meta is an arbitrary JSON object whose shape depends on the provider kind.

type CredentialBindingPatchRequest added in v0.64.5 

type CredentialBindingPatchRequest struct {
	DisplayName *string `json:"display_name" extensions:"x-nullable=true" example:"Renamed Cluster"`

} // @name CredentialBindingPatchRequest

CredentialBindingPatchRequest is the body for PATCH /api/workspaces/{id}/credentials/{kind}/{bindingId}. Only display_name is patchable at present.

type ExecutorConnectCommands added in v0.64.5 

type ExecutorConnectCommands struct {
	AgentIdentity string `json:"agent_identity" validate:"required"`

} // @name ExecutorConnectCommands

ExecutorConnectCommands holds the connect-command variants returned by the register endpoint. At present only the agent_identity variant is surfaced.

type ExecutorItem added in v0.64.5 

type ExecutorItem struct {
	ExeID          string     `json:"exe_id" validate:"required"`
	Name           string     `json:"name" validate:"required"`
	Description    string     `json:"description,omitempty"`
	IsDefault      bool       `json:"is_default"`
	IsOnline       bool       `json:"is_online"`
	LastSeenAt     *time.Time `json:"last_seen_at,omitempty" extensions:"x-nullable=true"`
	ClientIP       string     `json:"client_ip,omitempty"`
	ClientUA       string     `json:"client_ua,omitempty"`
	CodexVersion   string     `json:"codex_version,omitempty"`
	OS             string     `json:"os,omitempty"`
	ConnectedAt    *time.Time `json:"connected_at,omitempty" extensions:"x-nullable=true"`
	DisconnectedAt *time.Time `json:"disconnected_at,omitempty" extensions:"x-nullable=true"`

} // @name ExecutorItem

ExecutorItem is one entry returned by GET /api/workspaces/{wid}/executors. All session fields (client_ip, client_ua, codex_version, os, connected_at, disconnected_at) come from the last seen connection; they are omitted when the executor has never connected.

type ExecutorRegisterRequest added in v0.64.5 

type ExecutorRegisterRequest struct {
	Name        string `json:"name" validate:"required" example:"my-dev-machine"`
	Description string `json:"description,omitempty" example:"Main development laptop"`

} // @name ExecutorRegisterRequest

ExecutorRegisterRequest is the body for POST /api/workspaces/{wid}/executors.

type ExecutorRegisterResponse added in v0.64.5 

type ExecutorRegisterResponse struct {
	ExeID            string                  `json:"exe_id" validate:"required"`
	ConnectCommand   string                  `json:"connect_command,omitempty"`
	AgentIdentityJWT string                  `json:"agent_identity_jwt,omitempty"`
	ConnectCommands  ExecutorConnectCommands `json:"connect_commands,omitempty"`

} // @name ExecutorRegisterResponse

ExecutorRegisterResponse is returned (201) by POST /api/workspaces/{wid}/executors. agent_identity_jwt and connect_commands are only set when the codex auth shim is configured. connect_command is a convenience alias for connect_commands.agent_identity.

type ExecutorsClient added in v0.50.4 

type ExecutorsClient struct {
	// contains filtered or unexported fields
}

ExecutorsClient talks to codex-exec-gateway's user-management API on behalf of a session-authenticated agentserver user. Every request carries:

  • X-Internal-Secret: agentserver's INTERNAL_API_SECRET (matches the RequireAgentserverSecret middleware on the gateway side)
  • X-User-Id: the calling user's ID (gateway uses this for its own ownership ACL on executors)

func NewExecutorsClient added in v0.50.4 

func NewExecutorsClient(baseURL, secret string) *ExecutorsClient

func (*ExecutorsClient) Bind added in v0.50.4 

func (c *ExecutorsClient) Bind(ctx context.Context, userID, workspaceID, exeID, name, description string, isDefault bool) error

Bind attaches an existing executor to a workspace under the caller-supplied name (workspace-unique). description is optional.

func (*ExecutorsClient) List added in v0.50.4 

func (c *ExecutorsClient) List(ctx context.Context, userID, workspaceID string) ([]ListedExecutor, error)

List returns all executors bound to the workspace.

func (*ExecutorsClient) Register added in v0.50.4 

func (c *ExecutorsClient) Register(ctx context.Context, userID string, req RegisterExecutorRequest) (RegisterExecutorResponse, error)

Register creates a new executor owned by userID and returns the raw registration token (one-time).

func (*ExecutorsClient) Unbind added in v0.50.4 

func (c *ExecutorsClient) Unbind(ctx context.Context, userID, workspaceID, exeID string) error

Unbind removes an executor from a workspace.

func (*ExecutorsClient) Unregister added in v0.54.2 

func (c *ExecutorsClient) Unregister(ctx context.Context, userID, exeID string) error

Unregister deletes an executor row (and any of its bindings via CASCADE) from the gateway store. Used by the agentserver Register handler to clean up after a failed Bind so we don't leak orphan executors. Idempotent: 404 is treated as success.

type IMChannelListResponse added in v0.64.5 

type IMChannelListResponse struct {
	Channels []IMChannelResponse `json:"channels" validate:"required"`

} // @name IMChannelListResponse

IMChannelListResponse is the {"channels": [...]} envelope returned by GET /api/workspaces/{id}/im/channels.

type IMChannelPatchRequest added in v0.64.5 

type IMChannelPatchRequest struct {
	RequireMention *bool   `json:"require_mention" extensions:"x-nullable=true"`
	RoutingMode    *string `json:"routing_mode" extensions:"x-nullable=true" example:"codex"`

} // @name IMChannelPatchRequest

IMChannelPatchRequest is the body for PATCH /api/workspaces/{id}/im/channels/{channelId}. Both fields are optional — only the supplied keys are applied. routing_mode must be "nanoclaw" or "codex".

type IMChannelPatchResponse added in v0.64.5 

type IMChannelPatchResponse struct {
	Status string `json:"status" validate:"required" example:"updated"`

} // @name IMChannelPatchResponse

IMChannelPatchResponse is the body returned on success by PATCH /api/workspaces/{id}/im/channels/{channelId}.

type IMChannelResponse added in v0.64.5 

type IMChannelResponse struct {
	ID             string `json:"id" validate:"required"`
	WorkspaceID    string `json:"workspace_id" validate:"required"`
	Provider       string `json:"provider" validate:"required" example:"weixin"`
	BotID          string `json:"bot_id" validate:"required"`
	UserID         string `json:"user_id,omitempty"`
	RequireMention bool   `json:"require_mention"`
	RoutingMode    string `json:"routing_mode" validate:"required" example:"codex"`
	BoundAt        string `json:"bound_at" validate:"required"`

} // @name IMChannel

IMChannelResponse mirrors workspace_im_channels rows returned by GET /api/workspaces/{id}/im/channels via the imbridge service. user_id is omitted when not set (weixin sets it; telegram/matrix do not).

type IMMatrixConfigureRequest added in v0.64.5 

type IMMatrixConfigureRequest struct {
	HomeserverURL string `json:"homeserver_url" validate:"required" example:"https://matrix.example.com"`
	AccessToken   string `json:"access_token" validate:"required"`
	RecoveryKey   string `json:"recovery_key"` // optional, for E2EE

} // @name IMMatrixConfigureRequest

IMMatrixConfigureRequest is the body for POST .../im/matrix/configure. recovery_key is optional and only used to enable E2EE.

type IMMatrixConfigureResponse added in v0.64.5 

type IMMatrixConfigureResponse struct {
	Connected bool   `json:"connected" validate:"required"`
	BotID     string `json:"bot_id" validate:"required"`

} // @name IMMatrixConfigureResponse

IMMatrixConfigureResponse is returned by POST .../im/matrix/configure.

type IMSandboxBindRequest added in v0.64.5 

type IMSandboxBindRequest struct {
	ChannelID string `json:"channel_id" validate:"required"`

} // @name IMSandboxBindRequest

IMSandboxBindRequest is the body for POST /api/sandboxes/{id}/im/bind.

type IMSandboxBindResponse added in v0.64.5 

type IMSandboxBindResponse struct {
	Status string `json:"status" validate:"required" example:"bound"`

} // @name IMSandboxBindResponse

IMSandboxBindResponse is returned on success by POST /api/sandboxes/{id}/im/bind.

type IMSandboxUnbindResponse added in v0.64.5 

type IMSandboxUnbindResponse struct {
	Status string `json:"status" validate:"required" example:"unbound"`

} // @name IMSandboxUnbindResponse

IMSandboxUnbindResponse is returned on success by DELETE /api/sandboxes/{id}/im/bind.

type IMTelegramConfigureRequest added in v0.64.5 

type IMTelegramConfigureRequest struct {
	BotToken string `json:"bot_token" validate:"required" example:"123456:ABC-DEF..."`

} // @name IMTelegramConfigureRequest

IMTelegramConfigureRequest is the body for POST .../im/telegram/configure.

type IMTelegramConfigureResponse added in v0.64.5 

type IMTelegramConfigureResponse struct {
	Connected bool   `json:"connected" validate:"required"`
	BotID     string `json:"bot_id" validate:"required"`

} // @name IMTelegramConfigureResponse

IMTelegramConfigureResponse is returned by POST .../im/telegram/configure.

type IMWeixinQRStartResponse added in v0.64.5 

type IMWeixinQRStartResponse struct {
	QRCodeURL string `json:"qrcode_url" validate:"required"`
	Message   string `json:"message" validate:"required"`

} // @name IMWeixinQRStartResponse

IMWeixinQRStartResponse is returned by POST .../im/weixin/qr-start.

type IMWeixinQRWaitResponse added in v0.64.5 

type IMWeixinQRWaitResponse struct {
	Connected bool    `json:"connected" validate:"required"`
	Status    string  `json:"status" validate:"required" example:"wait"`
	Message   *string `json:"message,omitempty" extensions:"x-nullable=true"`
	QRCodeURL *string `json:"qrcode_url,omitempty" extensions:"x-nullable=true"`
	BotID     *string `json:"bot_id,omitempty" extensions:"x-nullable=true"`
	UserID    *string `json:"user_id,omitempty" extensions:"x-nullable=true"`

} // @name IMWeixinQRWaitResponse

IMWeixinQRWaitResponse is the polymorphic response from POST .../im/weixin/qr-wait. status values: "wait", "scaned", "confirmed", "expired", "binded_redirect", "verify_code_blocked", "need_verifycode". qrcode_url is only present when status is "expired" (new QR code generated). bot_id and user_id are only present when status is "confirmed".

type LLMConfigResponse added in v0.64.5 

type LLMConfigResponse struct {
	Configured bool       `json:"configured" validate:"required"`
	BaseURL    string     `json:"base_url"`
	APIKey     string     `json:"api_key"`
	Models     []LLMModel `json:"models,omitempty"`
	UpdatedAt  *string    `json:"updated_at" extensions:"x-nullable=true"`

} // @name LLMConfigResponse

LLMConfigResponse is the body returned by GET /api/workspaces/{id}/llm-config. api_key is masked (first 3 + "..." + last 4 chars) and is empty when no config exists.

type LLMConfigUpsertRequest added in v0.64.5 

type LLMConfigUpsertRequest struct {
	BaseURL string     `json:"base_url" validate:"required" example:"https://api.anthropic.com"`
	APIKey  string     `json:"api_key" example:"sk-ant-..."` // optional on update
	Models  []LLMModel `json:"models" validate:"required"`

} // @name LLMConfigUpsertRequest

LLMConfigUpsertRequest is the body for PUT /api/workspaces/{id}/llm-config. All three fields are required for a fresh config; for an update, omitting api_key retains the existing key.

type LLMConfigUpsertResponse added in v0.64.5 

type LLMConfigUpsertResponse struct {
	OK bool `json:"ok" validate:"required"`

} // @name LLMConfigUpsertResponse

LLMConfigUpsertResponse is the body returned by the upsert endpoint.

type LLMModel added in v0.64.5 

type LLMModel struct {
	ID   string `json:"id" validate:"required" example:"claude-opus-4-7"`
	Name string `json:"name" validate:"required" example:"Claude Opus 4.7"`

} // @name LLMModel

LLMModel is one entry in a workspace's per-model LLM config. id is the model identifier used in API calls; name is the human-readable label.

type LLMQuotaResponse added in v0.64.5 

type LLMQuotaResponse struct {
	DefaultMaxRPD     int                    `json:"default_max_rpd" validate:"required"`
	TodayRequestCount int                    `json:"today_request_count" validate:"required"`
	WorkspaceQuota    *LLMWorkspaceQuotaPart `json:"workspace_quota" extensions:"x-nullable=true"`

} // @name LLMQuotaResponse

LLMQuotaResponse mirrors the body the LLM proxy returns from its /internal/quotas/{workspaceId} endpoint, forwarded verbatim by GET /api/workspaces/{id}/llm-quota. workspace_quota is null when no per-workspace override is set.

type LLMWorkspaceQuotaPart added in v0.64.5 

type LLMWorkspaceQuotaPart struct {
	WorkspaceID string `json:"workspace_id" validate:"required"`
	MaxRPD      *int   `json:"max_rpd" extensions:"x-nullable=true"`
	UpdatedAt   string `json:"updated_at" validate:"required"`

} // @name LLMWorkspaceQuotaPart

LLMWorkspaceQuotaPart is the per-workspace quota override stored in the LLM proxy DB. max_rpd is null when no custom limit is configured.

type ListedExecutor added in v0.50.4 

type ListedExecutor struct {
	ExeID          string     `json:"exe_id"`
	Name           string     `json:"name"`
	Description    string     `json:"description"`
	IsDefault      bool       `json:"is_default"`
	LastSeenAt     *time.Time `json:"last_seen_at,omitempty"`
	ClientIP       string     `json:"client_ip,omitempty"`
	ClientUA       string     `json:"client_ua,omitempty"`
	CodexVersion   string     `json:"codex_version,omitempty"`
	OS             string     `json:"os,omitempty"`
	ConnectedAt    *time.Time `json:"connected_at,omitempty"`
	DisconnectedAt *time.Time `json:"disconnected_at,omitempty"`
	IsOnline       bool       `json:"is_online"`
}

ListedExecutor matches codex-exec-gateway's GET /api/codex-exec/workspaces/{wid}/executors element shape. Per v0.54.0, surfaced fields are binding-level (name + description) from workspace_executors, not the executor row.

type MemberAddRequest added in v0.64.5 

type MemberAddRequest struct {
	Email string `json:"email" validate:"required" example:"alice@example.com"`
	Role  string `json:"role" example:"developer"` // optional; defaults to "developer"

} // @name MemberAddRequest

MemberAddRequest is the body for POST /api/workspaces/{id}/members.

type MemberRoleUpdateRequest added in v0.64.5 

type MemberRoleUpdateRequest struct {
	Role string `json:"role" validate:"required" example:"maintainer"`

} // @name MemberRoleUpdateRequest

MemberRoleUpdateRequest is the body for PUT /api/workspaces/{id}/members/{userId}.

type ModelServerStatusResponse added in v0.64.5 

type ModelServerStatusResponse struct {
	Connected   bool       `json:"connected" validate:"required"`
	ProjectID   string     `json:"project_id,omitempty"`
	ProjectName string     `json:"project_name,omitempty"`
	Models      []LLMModel `json:"models,omitempty"`
	ConnectedAt string     `json:"connected_at,omitempty"`

} // @name ModelServerStatusResponse

ModelServerStatusResponse is returned by GET /api/workspaces/{id}/modelserver/status. When connected is false all other fields are absent. models entries have the same {id, name} shape as LLMModel.

type OperationRecord added in v0.64.5 

type OperationRecord struct {
	ID            string      `json:"id" validate:"required"`
	WorkspaceID   string      `json:"workspace_id" validate:"required"`
	UserID        *string     `json:"user_id,omitempty" extensions:"x-nullable=true"`
	Source        string      `json:"source" validate:"required" example:"codex"`
	ThreadID      *string     `json:"thread_id,omitempty" extensions:"x-nullable=true"`
	RequestID     *string     `json:"request_id,omitempty" extensions:"x-nullable=true"`
	EnvID         string      `json:"env_id" validate:"required"`
	Tool          string      `json:"tool" validate:"required" example:"shell"`
	Arguments     interface{} `json:"arguments,omitempty"`
	ArgumentsMeta interface{} `json:"arguments_meta,omitempty"`
	IsError       bool        `json:"is_error"`
	ResultSummary *string     `json:"result_summary,omitempty" extensions:"x-nullable=true"`
	ResultMeta    interface{} `json:"result_meta,omitempty"`
	StartedAt     string      `json:"started_at" validate:"required"`
	CompletedAt   string      `json:"completed_at" validate:"required"`
	DurationMs    int32       `json:"duration_ms" validate:"required"`
	NotebookPath  *string     `json:"notebook_path,omitempty" extensions:"x-nullable=true"`
	CellID        *string     `json:"cell_id,omitempty" extensions:"x-nullable=true"`

} // @name OperationRecord

OperationRecord is a single entry in the operations log. arguments, arguments_meta and result_meta are arbitrary JSON objects.

type RegisterExecutorRequest added in v0.50.4 

type RegisterExecutorRequest struct {
	DisplayName string `json:"display_name,omitempty"`
}

RegisterExecutorRequest matches codex-exec-gateway's POST /api/codex-exec/register body. Per v0.54.0, executors no longer carry a default_cwd; that field was useless to the LLM and confusing in the UI.

type RegisterExecutorResponse added in v0.50.4 

type RegisterExecutorResponse struct {
	ExeID string `json:"exe_id"`
}

RegisterExecutorResponse matches codex-exec-gateway's response. The pre-0.132 bcrypt registration_token is gone — auth on /cloud/.../register now uses the Agent Identity JWT.

type ResourceDefaults added in v0.7.0 

type ResourceDefaults struct {
	MaxWorkspacesPerUser     int
	MaxSandboxesPerWorkspace int
	MaxWorkspaceDriveSize    int64 // bytes
	MaxSandboxCPU            int   // millicores
	MaxSandboxMemory         int64 // bytes
	MaxIdleTimeout           int   // seconds
	WsMaxTotalCPU            int   // millicores
	WsMaxTotalMemory         int64 // bytes
	WsMaxIdleTimeout         int   // seconds
}

ResourceDefaults holds all resolved system-wide defaults.

type SandboxCreateRequest added in v0.64.5 

type SandboxCreateRequest struct {
	Name        string                 `json:"name" validate:"required" example:"my-sandbox"`
	Type        string                 `json:"type" example:"opencode"` // optional; default "opencode"
	CPU         *int                   `json:"cpu"`                     // optional; millicores, e.g. 500 or 2000
	Memory      *int64                 `json:"memory"`                  // optional; bytes, e.g. 536870912 (512Mi)
	IdleTimeout *int                   `json:"idle_timeout"`            // optional; seconds
	Metadata    map[string]interface{} `json:"metadata"`                // optional; arbitrary key-value metadata

} // @name SandboxCreateRequest

SandboxCreateRequest is the body for POST /api/workspaces/{wid}/sandboxes. All fields except name are optional and fall back to workspace/server defaults.

type SandboxLifecycleStatusResponse added in v0.64.5 

type SandboxLifecycleStatusResponse struct {
	Status string `json:"status" validate:"required" example:"pausing"`

} // @name SandboxLifecycleStatusResponse

SandboxLifecycleStatusResponse is the {"status": "pausing"} envelope returned by POST /api/sandboxes/{id}/pause and /resume. The status reflects the transition initiated, not the final state (those are async).

type SandboxRenameRequest added in v0.64.5 

type SandboxRenameRequest struct {
	Name string `json:"name" validate:"required" example:"renamed-sandbox"`

} // @name SandboxRenameRequest

SandboxRenameRequest is the body for PATCH /api/sandboxes/{id}.

type SandboxUsageResponse added in v0.64.5 

type SandboxUsageResponse struct {
	Usage []SandboxUsageSummary `json:"usage" validate:"required"`
	Since *string               `json:"since,omitempty" extensions:"x-nullable=true" example:"2026-01-01T00:00:00Z"`

} // @name SandboxUsage

SandboxUsageResponse mirrors the body the LLM proxy returns from its /internal/usage?sandbox_id={id} endpoint, forwarded verbatim by GET /api/sandboxes/{id}/usage. usage is the per-provider/model breakdown; since is set only when the caller supplied a ?since= query param.

type SandboxUsageSummary added in v0.64.5 

type SandboxUsageSummary struct {
	Provider                 string `json:"provider" validate:"required" example:"anthropic"`
	Model                    string `json:"model" validate:"required" example:"claude-sonnet-4-6"`
	InputTokens              int64  `json:"input_tokens" validate:"required"`
	OutputTokens             int64  `json:"output_tokens" validate:"required"`
	CacheCreationInputTokens int64  `json:"cache_creation_input_tokens" validate:"required"`
	CacheReadInputTokens     int64  `json:"cache_read_input_tokens" validate:"required"`
	RequestCount             int64  `json:"request_count" validate:"required"`

} // @name SandboxUsageSummary

SandboxUsageSummary is one row in the per-provider/model breakdown returned by GET /api/sandboxes/{id}/usage. It mirrors llmproxy.UsageSummary.

type Server 

type Server struct {
	Auth                      *auth.Auth
	OIDC                      *auth.OIDCManager
	DB                        *db.DB
	Sandboxes                 *sbxstore.Store
	ProcessManager            process.Manager
	DriveManager              storage.DriveManager
	NamespaceManager          *namespace.Manager
	TunnelRegistry            *tunnel.Registry
	StaticFS                  fs.FS
	BaseDomains               []string // e.g. ["agentserver.dev", "agent.cs.ac.cn"] (first is primary)
	OpencodeSubdomainPrefix   string   // e.g. "code" — subdomain: code-{id}.{baseDomain}
	OpenclawSubdomainPrefix   string   // e.g. "claw" — subdomain: claw-{id}.{baseDomain}
	ClaudeCodeSubdomainPrefix string   // e.g. "claude" — subdomain: claude-{id}.{baseDomain}
	JupyterSubdomainPrefix    string   // e.g. "jupyter" — subdomain: jupyter-{id}.{baseDomain}
	PasswordAuthEnabled       bool     // when false, /api/auth/login and /api/auth/register are not registered
	LLMProxyURL               string   // base URL for the llmproxy service (e.g. "http://agentserver-llmproxy:8081")

	// IMBridgeURL is the base URL of the standalone imbridge service
	// (e.g. "http://agentserver-imbridge:8083"). When set, IM API routes
	// are reverse-proxied to the imbridge service.
	IMBridgeURL string

	// ModelServer OAuth
	ModelserverOAuthClientID      string
	ModelserverOAuthClientSecret  string
	ModelserverOAuthAuthURL       string
	ModelserverOAuthTokenURL      string
	ModelserverOAuthIntrospectURL string
	ModelserverOAuthRedirectURI   string
	ModelserverProxyURL           string
	DatabaseURL                   string // PostgreSQL connection URL (needed for Matrix E2EE crypto DB)

	// Hydra OAuth2 (for agent Device Flow)
	HydraClient    *auth.HydraClient
	HydraPublicURL string // internal URL for reverse proxy (e.g. "http://hydra-public:4444")

	// Credential proxy
	EncryptionKey      []byte // AES-256 key for credential_bindings auth_blob
	CredproxyPublicURL string // URL sandboxes use to reach credentialproxy

	// Codex exec gateway
	ExecutorsClient            *ExecutorsClient
	CodexExecGatewayPublicHost string // e.g. "codex-exec.example.com" — used to compose connect commands

	// CodexAuth is the self-hosted codex 0.132+ auth shim (PKCE / device
	// flow / JWKS / Agent Identity). Mounted under /codex-auth/* when set.
	CodexAuth *codexauth.Server

	// CodexAuthIssuerURL is the public-facing issuer URL for the codex
	// auth shim, e.g. "https://agent.cs.ac.cn/codex-auth". Mirrors the
	// value used to construct CodexAuth.IssuerURL; surfaced separately so
	// register-executor can build connect commands that point clients at
	// the right `codex login --issuer` / token-refresh endpoints.
	CodexAuthIssuerURL string

	// OperationsRetention is the TTL for rows in the operations table.
	// 0 disables the background retention loop. Configurable via
	// AGENTSERVER_OPERATIONS_RETENTION_DAYS (default 90).
	OperationsRetention time.Duration
	// contains filtered or unexported fields
}

func New 

func New(a *auth.Auth, oidcMgr *auth.OIDCManager, database *db.DB, sandboxStore *sbxstore.Store, processManager process.Manager, driveManager storage.DriveManager, nsMgr *namespace.Manager, tunnelReg *tunnel.Registry, staticFS fs.FS, passwordAuthEnabled bool) *Server

func (*Server) Close added in v0.60.14 

func (s *Server) Close()

Close releases resources owned by the Server. Safe to call after Router() returns; a no-op if called before Router() or if the codex routing path was not configured.

func (*Server) GetEffectiveIdleTimeout added in v0.7.0 

func (s *Server) GetEffectiveIdleTimeout() time.Duration

GetEffectiveIdleTimeout is the exported version for use by cmd/serve.go.

func (*Server) Router 

func (s *Server) Router() http.Handler

func (*Server) StartRetentionLoop added in v0.57.0 

func (s *Server) StartRetentionLoop(ctx context.Context, ttl time.Duration, every time.Duration)

StartRetentionLoop is the exported entry point for the server's main lifecycle to launch the retention loop in a goroutine.

type TraceDetailResponse added in v0.64.5 

type TraceDetailResponse struct {
	Trace    TraceRecord    `json:"trace" validate:"required"`
	Requests []TraceRequest `json:"requests" validate:"required"`

} // @name TraceDetailResponse

TraceDetailResponse is the body returned by /traces/{traceId} endpoints. It pairs the trace metadata with the list of per-request records.

type TraceListResponse added in v0.64.5 

type TraceListResponse struct {
	Traces []TraceRecord `json:"traces" validate:"required"`
	Total  int64         `json:"total"`

} // @name TraceListResponse

TraceListResponse wraps a list of trace records. total is the total count for pagination (set by llmproxy).

type TraceRecord added in v0.64.5 

type TraceRecord struct {
	ID                       string `json:"id" validate:"required"`
	SandboxID                string `json:"sandbox_id" validate:"required"`
	WorkspaceID              string `json:"workspace_id" validate:"required"`
	Source                   string `json:"source" validate:"required" example:"codex"`
	CreatedAt                string `json:"created_at" validate:"required"`
	UpdatedAt                string `json:"updated_at" validate:"required"`
	RequestCount             int64  `json:"request_count" validate:"required"`
	TotalInputTokens         int64  `json:"total_input_tokens" validate:"required"`
	TotalOutputTokens        int64  `json:"total_output_tokens" validate:"required"`
	TotalCacheReadTokens     int64  `json:"total_cache_read_tokens" validate:"required"`
	TotalCacheCreationTokens int64  `json:"total_cache_creation_tokens" validate:"required"`
	Models                   string `json:"models,omitempty"`

} // @name TraceRecord

TraceRecord is one entry in the LLM trace list returned by the traces endpoints. All token/request count fields come from the llmproxy aggregation.

type TraceRequest added in v0.64.5 

type TraceRequest struct {
	ID                       string `json:"id" validate:"required"`
	TraceID                  string `json:"trace_id,omitempty"`
	SandboxID                string `json:"sandbox_id" validate:"required"`
	WorkspaceID              string `json:"workspace_id" validate:"required"`
	Provider                 string `json:"provider" validate:"required"`
	Model                    string `json:"model" validate:"required"`
	MessageID                string `json:"message_id,omitempty"`
	InputTokens              int64  `json:"input_tokens" validate:"required"`
	OutputTokens             int64  `json:"output_tokens" validate:"required"`
	CacheCreationInputTokens int64  `json:"cache_creation_input_tokens" validate:"required"`
	CacheReadInputTokens     int64  `json:"cache_read_input_tokens" validate:"required"`
	Streaming                bool   `json:"streaming"`
	Duration                 int64  `json:"duration" validate:"required"`
	TTFT                     int64  `json:"ttft"`
	CreatedAt                string `json:"created_at" validate:"required"`

} // @name TraceRequest

TraceRequest is one row in the requests array of TraceDetailResponse. Fields mirror what the LLM proxy emits for a single API call (TokenUsage).

type WorkspaceAPIKey added in v0.64.12 

type WorkspaceAPIKey struct {
	ID         string   `json:"id" validate:"required" example:"wak_a1b2c3d4"`
	Name       string   `json:"name" validate:"required"`
	Prefix     string   `json:"prefix" validate:"required" example:"wak_a1b2c3d4"`
	Scopes     []string `json:"scopes" validate:"required"`
	CreatedAt  string   `json:"created_at" validate:"required"`
	LastUsedAt *string  `json:"last_used_at" extensions:"x-nullable=true"`
	RevokedAt  *string  `json:"revoked_at" extensions:"x-nullable=true"`

} // @name WorkspaceAPIKey

WorkspaceAPIKey is one row in the list response. Secret is NEVER included here — only the prefix for display.

type WorkspaceAPIKeyMintRequest added in v0.64.12 

type WorkspaceAPIKeyMintRequest struct {
	Name   string   `json:"name" validate:"required" example:"my-bot-integration"`
	Scopes []string `json:"scopes" validate:"required" example:"[\"turns:submit\"]"`

} // @name WorkspaceAPIKeyMintRequest

WorkspaceAPIKeyMintRequest is the body for POST /api/workspaces/{wid}/api-keys. Scopes must be non-empty and every entry must reference an Available scope in the catalog (see GET .../api-keys/scopes).

type WorkspaceAPIKeyMintResponse added in v0.64.12 

type WorkspaceAPIKeyMintResponse struct {
	ID        string   `json:"id" validate:"required" example:"wak_a1b2c3d4"`
	Name      string   `json:"name" validate:"required"`
	Prefix    string   `json:"prefix" validate:"required" example:"wak_a1b2c3d4"`
	Secret    string   `json:"secret" validate:"required" example:"wak_a1b2c3d4_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"`
	Scopes    []string `json:"scopes" validate:"required"`
	CreatedAt string   `json:"created_at" validate:"required"`

} // @name WorkspaceAPIKeyMintResponse

WorkspaceAPIKeyMintResponse is the body returned by the mint endpoint IMMEDIATELY after creation. The secret field is returned ONCE here and never appears in any subsequent API response.

type WorkspaceCreateRequest added in v0.64.5 

type WorkspaceCreateRequest struct {
	Name string `json:"name" validate:"required" example:"My Workspace"`

} // @name WorkspaceCreateRequest

WorkspaceCreateRequest is the body for POST /api/workspaces.

type WorkspaceDefaults added in v0.9.0 

type WorkspaceDefaults struct {
	MaxSandboxes     int
	MaxSandboxCPU    int   // millicores
	MaxSandboxMemory int64 // bytes
	MaxIdleTimeout   int   // seconds
	MaxTotalCPU      int   // millicores
	MaxTotalMemory   int64 // bytes
	MaxDriveSize     int64 // bytes
}

WorkspaceDefaults holds workspace-level resolved defaults (system defaults <- workspace_quotas override).

type WorkspaceDefaultsResponse added in v0.64.5 

type WorkspaceDefaultsResponse struct {
	MaxSandboxCPU    int   `json:"max_sandbox_cpu" validate:"required"`
	MaxSandboxMemory int64 `json:"max_sandbox_memory" validate:"required"`
	MaxIdleTimeout   int   `json:"max_idle_timeout" validate:"required"`
	MaxSandboxes     int   `json:"max_sandboxes" validate:"required"`
	CurrentSandboxes int   `json:"current_sandboxes" validate:"required"`

} // @name WorkspaceDefaultsResponse

WorkspaceDefaultsResponse is returned by GET /api/workspaces/{wid}/defaults. It provides the effective quota limits for the workspace and the current sandbox count.

type WorkspaceOperationsResponse added in v0.64.5 

type WorkspaceOperationsResponse struct {
	Operations []OperationRecord `json:"operations" validate:"required"`

} // @name WorkspaceOperationsResponse

WorkspaceOperationsResponse is returned by GET /api/workspaces/{id}/operations.

type WorkspaceQuotaResponse added in v0.64.5 

type WorkspaceQuotaResponse struct {
	Current int `json:"current" validate:"required"`
	Max     int `json:"max" validate:"required"`

} // @name WorkspaceQuotaResponse

WorkspaceQuotaResponse is the {"current": int, "max": int} envelope returned by GET /api/workspaces/quota.

type WorkspaceRenameRequest added in v0.64.5 

type WorkspaceRenameRequest struct {
	Name string `json:"name" validate:"required" example:"Renamed Workspace"`

} // @name WorkspaceRenameRequest

WorkspaceRenameRequest is the body for PATCH /api/workspaces/{id}.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.