Codex.AppServer (Codex SDK v0.17.0)

@type connect_opts() :: [
  init_timeout_ms: pos_integer(),
  client_name: String.t(),
  client_title: String.t(),
  client_version: String.t(),
  experimental_api: boolean(),
  execution_surface: CliSubprocessCore.ExecutionSurface.t() | map() | keyword(),
  cwd: String.t(),
  process_env: map() | keyword(),
  env: map() | keyword(),
  oauth: keyword()
]

Options for launching and initializing a managed codex app-server child process.

cwd and process_env / env apply to the child process itself. Per-thread working directories still belong on thread/start, thread/resume, or Codex.Thread.Options.

connect_remote_opts()

@type connect_remote_opts() :: [
  init_timeout_ms: pos_integer(),
  client_name: String.t(),
  client_title: String.t(),
  client_version: String.t(),
  experimental_api: boolean(),
  auth_token: String.t(),
  auth_token_env: String.t(),
  governed_authority: map() | keyword(),
  cwd: String.t(),
  process_env: map() | keyword(),
  env: map() | keyword(),
  oauth: keyword()
]

connection()

@type connection() :: pid()

Functions

alive?(conn)

@spec alive?(connection()) :: boolean()

apps_list(conn, opts \\ [])

@spec apps_list(
  connection(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Lists available apps/connectors.

collaboration_mode_list(conn)

@spec collaboration_mode_list(connection()) :: {:ok, map()} | {:error, term()}

Lists collaboration mode presets (experimental).

command_exec(conn, command, opts \\ [])

@spec command_exec(connection(), [String.t()], keyword()) ::
  {:ok, map()} | {:error, term()}

command_exec_resize(conn, process_id, size)

@spec command_exec_resize(connection(), String.t(), map() | keyword()) ::
  {:ok, map()} | {:error, term()}

command_exec_terminate(conn, process_id)

@spec command_exec_terminate(connection(), String.t()) ::
  {:ok, map()} | {:error, term()}

command_exec_write(conn, process_id, opts \\ [])

@spec command_exec_write(connection(), String.t(), keyword()) ::
  {:ok, map()} | {:error, term()}

Writes bytes to a running command/exec session.

command_write_stdin(conn, process_id, stdin, opts \\ [])

@spec command_write_stdin(connection(), String.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, term()}

Backwards-compatible alias for command_exec_write/3 using raw stdin text.

config_batch_write(conn, edits, opts \\ [])

@spec config_batch_write(connection(), [map()], keyword()) ::
  {:ok, map()} | {:error, term()}

config_read(conn, opts \\ [])

@spec config_read(
  connection(),
  keyword()
) :: {:ok, map()} | {:error, term()}

config_requirements(conn)

@spec config_requirements(connection()) :: {:ok, map()} | {:error, term()}

Reads config requirements enforced by the server (if any).

config_write(conn, key_path, value, opts \\ [])

@spec config_write(connection(), String.t(), term(), keyword()) ::
  {:ok, map()} | {:error, term()}

connect(codex_opts, opts \\ [])

@spec connect(Codex.Options.t(), connect_opts()) ::
  {:ok, connection()} | {:error, term()}

Starts a supervised codex app-server subprocess and completes the initialize handshake.

Use cwd and process_env (or the env alias) when the app-server child must run with an isolated working directory or CODEX_HOME without mutating the caller's shell environment.

connect_remote(websocket_url, opts \\ [])

@spec connect_remote(String.t(), connect_remote_opts()) ::
  {:ok, connection()} | {:error, term()}

Connects to a remote websocket-backed app-server endpoint and completes the initialize handshake.

device_key_create(conn, params)

@spec device_key_create(connection(), map() | keyword()) ::
  {:ok, map()} | {:error, term()}

Creates a controller-local device key.

device_key_public(conn, key_id)

@spec device_key_public(connection(), String.t()) :: {:ok, map()} | {:error, term()}

Reads device-key public metadata by key id.

device_key_sign(conn, key_id, payload)

@spec device_key_sign(connection(), String.t(), map()) ::
  {:ok, map()} | {:error, term()}

Signs a structured device-key payload with a controller-local key.

disconnect(conn)

@spec disconnect(connection()) :: :ok

environment_add(conn, environment_id, exec_server_url, opts \\ [])

@spec environment_add(connection(), String.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, term()}

Registers an execution environment backed by an exec-server websocket.

environment_info(conn, environment_id)

@spec environment_info(connection(), String.t()) :: {:ok, map()} | {:error, term()}

Reads shell and cwd metadata for a registered execution environment.

experimental_feature_enablement_set(conn, enablement \\ %{})

@spec experimental_feature_enablement_set(connection(), map() | keyword()) ::
  {:ok, map()} | {:error, term()}

experimental_feature_list(conn, opts \\ [])

@spec experimental_feature_list(
  connection(),
  keyword()
) :: {:ok, map()} | {:error, term()}

external_agent_config_detect(conn, opts \\ [])

@spec external_agent_config_detect(
  connection(),
  keyword()
) :: {:ok, map()} | {:error, term()}

external_agent_config_import(conn, migration_items)

@spec external_agent_config_import(connection(), [map()]) ::
  {:ok, map()} | {:error, term()}

feedback_upload(conn, opts)

@spec feedback_upload(
  connection(),
  keyword()
) :: {:ok, map()} | {:error, term()}

fs_copy(conn, source_path, destination_path, opts \\ [])

@spec fs_copy(connection(), String.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, term()}

Copies a file or directory via the app-server filesystem API.

fs_create_directory(conn, path, opts \\ [])

@spec fs_create_directory(connection(), String.t(), keyword()) ::
  {:ok, map()} | {:error, term()}

Creates a directory via the app-server filesystem API.

fs_get_metadata(conn, path)

@spec fs_get_metadata(connection(), String.t()) :: {:ok, map()} | {:error, term()}

Fetches file or directory metadata via the app-server filesystem API.

fs_read_directory(conn, path)

@spec fs_read_directory(connection(), String.t()) :: {:ok, map()} | {:error, term()}

Lists directory entries via the app-server filesystem API.

fs_read_file(conn, path)

@spec fs_read_file(connection(), String.t()) :: {:ok, map()} | {:error, term()}

Reads a file via the app-server filesystem API, returning a base64 payload.

fs_remove(conn, path, opts \\ [])

@spec fs_remove(connection(), String.t(), keyword()) ::
  {:ok, map()} | {:error, term()}

Removes a file or directory via the app-server filesystem API.

fs_unwatch(conn, watch_id)

@spec fs_unwatch(connection(), String.t()) :: {:ok, map()} | {:error, term()}

Stops a prior filesystem watch.

fs_watch(conn, watch_id, path)

@spec fs_watch(connection(), String.t(), String.t()) ::
  {:ok, map()} | {:error, term()}

Starts filesystem change notifications for an absolute file or directory path.

fs_write_file(conn, path, data_base64)

@spec fs_write_file(connection(), String.t(), String.t()) ::
  {:ok, map()} | {:error, term()}

Writes base64-encoded file contents via the app-server filesystem API.

fuzzy_file_search(conn, query, opts \\ [])

@spec fuzzy_file_search(connection(), String.t(), keyword()) ::
  {:ok, map()} | {:error, term()}

fuzzy_file_search_session_start(conn, session_id, roots)

@spec fuzzy_file_search_session_start(connection(), String.t(), [String.t()]) ::
  {:ok, map()} | {:error, term()}

fuzzy_file_search_session_stop(conn, session_id)

@spec fuzzy_file_search_session_stop(connection(), String.t()) ::
  {:ok, map()} | {:error, term()}

fuzzy_file_search_session_update(conn, session_id, query)

@spec fuzzy_file_search_session_update(connection(), String.t(), String.t()) ::
  {:ok, map()} | {:error, term()}

marketplace_add(conn, source, opts \\ [])

@spec marketplace_add(connection(), String.t(), keyword()) ::
  {:ok, map()} | {:error, term()}

Adds a marketplace source through the app-server marketplace API.

marketplace_remove(conn, marketplace_name)

@spec marketplace_remove(connection(), String.t()) :: {:ok, map()} | {:error, term()}

Removes an installed marketplace by name.

marketplace_upgrade(conn, opts \\ [])

@spec marketplace_upgrade(
  connection(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Upgrades one installed marketplace or all marketplaces when no name is provided.

memory_reset(conn)

@spec memory_reset(connection()) :: {:ok, map()} | {:error, term()}

model_list(conn, opts \\ [])

@spec model_list(
  connection(),
  keyword()
) :: {:ok, map()} | {:error, term()}

model_provider_capabilities_read(conn)

@spec model_provider_capabilities_read(connection()) ::
  {:ok, map()} | {:error, term()}

Reads the active model provider's capability flags (namespace tools, image generation, web search).

permission_profile_list(conn, opts \\ [])

@spec permission_profile_list(connection(), map() | keyword()) ::
  {:ok, map()} | {:error, term()}

Lists available named permission profiles (id, description, allowed status).

plugin_install(conn, marketplace_path, plugin_name, opts \\ [])

@spec plugin_install(connection(), String.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, term()}

Installs a plugin via the app-server plugin API and returns the raw response map.

For typed structs, use plugin_install_typed/4.

plugin_install_typed(conn, marketplace_path, plugin_name, opts \\ [])

@spec plugin_install_typed(connection(), String.t(), String.t(), keyword()) ::
  {:ok, Codex.Protocol.Plugin.InstallResponse.t()} | {:error, term()}

Installs a plugin via the app-server plugin API and parses the response into Codex.Protocol.Plugin.InstallResponse.

The raw plugin_install/4 wrapper remains available and still returns the original map payload.

plugin_list(conn, opts \\ [])

@spec plugin_list(
  connection(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Lists plugin marketplaces via the app-server plugin API and returns the raw response map.

For typed structs, use plugin_list_typed/2.

plugin_list_typed(conn, opts \\ [])

@spec plugin_list_typed(
  connection(),
  keyword()
) :: {:ok, Codex.Protocol.Plugin.ListResponse.t()} | {:error, term()}

Lists plugin marketplaces via the app-server plugin API and parses the response into Codex.Protocol.Plugin.ListResponse.

The raw plugin_list/2 wrapper remains available and still returns the original map payload.

plugin_read(conn, marketplace_path, plugin_name)

@spec plugin_read(connection(), String.t(), String.t()) ::
  {:ok, map()} | {:error, term()}

Reads plugin details from a marketplace entry via the app-server plugin API and returns the raw response map.

For typed structs, use plugin_read_typed/3.

plugin_read_typed(conn, marketplace_path, plugin_name)

@spec plugin_read_typed(connection(), String.t(), String.t()) ::
  {:ok, Codex.Protocol.Plugin.ReadResponse.t()} | {:error, term()}

Reads plugin details from a marketplace entry via the app-server plugin API and parses the response into Codex.Protocol.Plugin.ReadResponse.

The raw plugin_read/3 wrapper remains available and still returns the original map payload.

plugin_uninstall(conn, plugin_id, opts \\ [])

@spec plugin_uninstall(connection(), String.t(), keyword()) ::
  {:ok, map()} | {:error, term()}

Uninstalls a plugin via the app-server plugin API and returns the raw response map.

For typed structs, use plugin_uninstall_typed/3.

plugin_uninstall_typed(conn, plugin_id, opts \\ [])

@spec plugin_uninstall_typed(connection(), String.t(), keyword()) ::
  {:ok, Codex.Protocol.Plugin.UninstallResponse.t()} | {:error, term()}

Uninstalls a plugin via the app-server plugin API and parses the response into Codex.Protocol.Plugin.UninstallResponse.

The raw plugin_uninstall/3 wrapper remains available and still returns the original map payload.

request_typed(conn, method, params, response_module, opts \\ [])

@spec request_typed(
  connection(),
  String.t(),
  map() | keyword() | struct() | nil,
  module(),
  keyword()
) :: {:ok, struct()} | {:error, term()}

Sends an app-server request and parses the response with a typed response module.

When params is a typed params struct, the struct module's to_map/1 is used for wire encoding. For the typed plugin APIs, plain maps and keywords are normalized through the matching Codex.Protocol.Plugin.*Params module before the request is sent.

respond(conn, id, result)

@spec respond(connection(), String.t() | integer(), map()) :: :ok | {:error, term()}

review_start(conn, thread_id, target, opts \\ [])

@spec review_start(connection(), String.t(), term(), keyword()) ::
  {:ok, map()} | {:error, term()}

skills_config_write(conn, path, enabled)

@spec skills_config_write(connection(), String.t(), boolean()) ::
  {:ok, map()} | {:error, term()}

Writes a skills config entry enabling or disabling a skill by path.

skills_list(conn, opts \\ [])

@spec skills_list(
  connection(),
  keyword()
) :: {:ok, map()} | {:error, term()}

skills_remote_export(conn, hazelnut_id)

@spec skills_remote_export(connection(), String.t()) ::
  {:ok, map()} | {:error, term()}

skills_remote_list(conn, opts \\ [])

@spec skills_remote_list(
  connection(),
  keyword()
) :: {:ok, map()} | {:error, term()}

thread_archive(conn, thread_id)

@spec thread_archive(connection(), String.t()) :: :ok | {:error, term()}

thread_background_terminals_clean(conn, thread_id)

@spec thread_background_terminals_clean(connection(), String.t()) ::
  {:ok, map()} | {:error, term()}

thread_background_terminals_list(conn, thread_id, opts \\ [])

@spec thread_background_terminals_list(connection(), String.t(), map() | keyword()) ::
  {:ok, map()} | {:error, term()}

thread_background_terminals_terminate(conn, thread_id, process_id)

@spec thread_background_terminals_terminate(connection(), String.t(), String.t()) ::
  {:ok, map()} | {:error, term()}

thread_compact(conn, thread_id)

@spec thread_compact(connection(), String.t()) :: {:ok, map()} | {:error, term()}

Starts server-side context compaction for a thread.

thread_compact_start(conn, thread_id)

@spec thread_compact_start(connection(), String.t()) ::
  {:ok, map()} | {:error, term()}

Explicit alias for thread_compact/2.

thread_delete(conn, thread_id)

@spec thread_delete(connection(), String.t()) :: {:ok, map()} | {:error, term()}

thread_fork(conn, thread_id, params \\ %{})

@spec thread_fork(connection(), String.t(), map() | keyword()) ::
  {:ok, map()} | {:error, term()}

thread_inject_items(conn, thread_id, items)

@spec thread_inject_items(connection(), String.t(), [map()]) ::
  {:ok, map()} | {:error, term()}

thread_items_list(conn, thread_id, opts \\ [])

@spec thread_items_list(connection(), String.t(), keyword()) ::
  {:ok, map()} | {:error, term()}

thread_list(conn, opts \\ [])

@spec thread_list(
  connection(),
  keyword()
) :: {:ok, map()} | {:error, term()}

thread_loaded_list(conn, opts \\ [])

@spec thread_loaded_list(
  connection(),
  keyword()
) :: {:ok, map()} | {:error, term()}

thread_memory_mode_set(conn, thread_id, mode)

@spec thread_memory_mode_set(connection(), String.t(), atom() | String.t()) ::
  {:ok, map()} | {:error, term()}

thread_metadata_update(conn, thread_id, params)

@spec thread_metadata_update(connection(), String.t(), map() | keyword()) ::
  {:ok, map()} | {:error, term()}

thread_name_set(conn, thread_id, name)

@spec thread_name_set(connection(), String.t(), String.t()) ::
  {:ok, map()} | {:error, term()}

thread_read(conn, thread_id, opts \\ [])

@spec thread_read(connection(), String.t(), keyword()) ::
  {:ok, map()} | {:error, term()}

thread_realtime_append_audio(conn, thread_id, audio)

@spec thread_realtime_append_audio(connection(), String.t(), map() | keyword()) ::
  {:ok, map()} | {:error, term()}

thread_realtime_append_speech(conn, thread_id, text)

@spec thread_realtime_append_speech(connection(), String.t(), String.t()) ::
  {:ok, map()} | {:error, term()}

thread_realtime_append_text(conn, thread_id, text)

@spec thread_realtime_append_text(connection(), String.t(), String.t()) ::
  {:ok, map()} | {:error, term()}

thread_realtime_list_voices(conn)

@spec thread_realtime_list_voices(connection()) :: {:ok, map()} | {:error, term()}

thread_realtime_start(conn, thread_id, prompt, opts \\ [])

@spec thread_realtime_start(connection(), String.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, term()}

thread_realtime_stop(conn, thread_id)

@spec thread_realtime_stop(connection(), String.t()) ::
  {:ok, map()} | {:error, term()}

thread_resume(conn, thread_id, params \\ %{})

@spec thread_resume(connection(), String.t(), map() | keyword()) ::
  {:ok, map()} | {:error, term()}

thread_rollback(conn, thread_id, num_turns)

@spec thread_rollback(connection(), String.t(), pos_integer()) ::
  {:ok, map()} | {:error, term()}

thread_search(conn, opts)

@spec thread_search(
  connection(),
  keyword()
) :: {:ok, map()} | {:error, term()}

thread_search(conn, search_term, opts \\ [])

@spec thread_search(connection(), String.t(), keyword()) ::
  {:ok, map()} | {:error, term()}

thread_settings_update(conn, thread_id, params \\ [])

@spec thread_settings_update(connection(), String.t(), map() | keyword()) ::
  {:ok, map()} | {:error, term()}

Updates persistent settings for subsequent turns on a thread.

Accepts cwd, approval_policy, approvals_reviewer, sandbox_policy, permissions, model, service_tier (double-option: omit to leave unchanged, pass nil/:clear to explicitly clear it), effort, summary, and collaboration_mode. The app-server only acknowledges the update is queued; wait for the thread/settings/updated notification for the applied result.

thread_shell_command(conn, thread_id, command)

@spec thread_shell_command(connection(), String.t(), String.t()) ::
  {:ok, map()} | {:error, term()}

Runs a thread-bound shell command via the app-server ! workflow.

thread_start(conn, params \\ %{})

@spec thread_start(connection(), map() | keyword()) :: {:ok, map()} | {:error, term()}

thread_turns_list(conn, thread_id, opts \\ [])

@spec thread_turns_list(connection(), String.t(), keyword()) ::
  {:ok, map()} | {:error, term()}

thread_unarchive(conn, thread_id)

@spec thread_unarchive(connection(), String.t()) :: {:ok, map()} | {:error, term()}

thread_unsubscribe(conn, thread_id)

@spec thread_unsubscribe(connection(), String.t()) :: {:ok, map()} | {:error, term()}

turn_interrupt(conn, thread_id, turn_id)

@spec turn_interrupt(connection(), String.t(), String.t()) :: :ok | {:error, term()}

turn_start(conn, thread_id, input, opts \\ [])

@spec turn_start(connection(), String.t(), String.t() | [map()], keyword()) ::
  {:ok, map()} | {:error, term()}

turn_steer(conn, thread_id, input, opts \\ [])

@spec turn_steer(connection(), String.t(), String.t() | [map()], keyword()) ::
  {:ok, map()} | {:error, term()}

unsubscribe(conn)

@spec unsubscribe(connection()) :: :ok

windows_sandbox_setup_start(conn, mode, opts \\ [])

@spec windows_sandbox_setup_start(connection(), atom() | String.t(), keyword()) ::
  {:ok, map()} | {:error, term()}