Automation with Oda

DataMind Oda can work without the app window: a script can give it one task and read the answer, a program of yours can drive chats over standard input and output, and an automation client can manage sessions of its own. Use this page to pick the entry point and see what each one needs; the linked pages hold the full detail.

Pick the entry point

• No app window is involved. Each entry point runs Oda as its own process, and none of them serves the interface. How a mode is started, with its options, is on DataMind Oda on the command line. To run the Oda interface in a browser instead, see Oda in the browser.
• Three serving profiles. The automation profile (acp) serves clients that speak the Agent Client Protocol. The SDK profile (sdk) serves Oda SDK clients, which start a runtime of their own. The minimal runtime (sdk-minimal) is a small standalone runtime for SDK clients; see The minimal runtime.

Run one task and read the answer

A one-off run (the headless mode) answers a single task and exits.

1. Give the task as words on the command line, or send it on standard input.
2. Read the answer on standard output; the working notes (the model's reasoning) and any diagnostics go to standard error, so a script reads the answer without filtering it.
3. Read the exit code: 0 when the task completed, 1 when it did not, including a run that finished without an answer.

• A blank task is refused before anything runs.
• Continue an earlier run. Name the chat the earlier run saved, and the new task runs as its next message; a chat Oda does not know fails before the task runs: session "<id>" does not exist; omit --session-id to start a new Session.
• A run can report events instead of an answer. When a one-off run is asked for a JSON event stream, it writes one event per line instead of the final answer, so a program can follow the run as it works. The events and their bounds are on Headless runs.
• A model connection is needed. A run needs a model credential before it can answer: sign in to your DataMind server, or provide a key through Settings > Models (Set up models and providers). Until a credential resolves, model requests fail.

Drive chats from your own program

The Oda SDK serves a program of yours: a client starts an Oda runtime and talks to it over standard input and output with newline-delimited JSON-RPC messages. One runtime serves one client, from the first message until the client disconnects.

1. The client sends initialize with the working folder and the model route: provider, model, and, optionally, a reasoning effort and a token cap. Prompts are refused until the handshake completes.
2. The client sends session/prompt; the message is queued and the reply is a receipt, not an answer.
3. The work arrives as session.event notifications, and session.status reports the whole agent as running until it is idle, which means the turn has settled.
4. The client sends shutdown; the runtime flushes what it wrote and exits.

• A token-limit stop is not a finished run. A run cut off at its token limit is reported as a failure by default, and a runtime can be configured to treat max-token endings as successful results.
• A small standalone runtime. The sdk-minimal runtime serves an SDK client with one model adapter and a single shell tool, and it runs with full access to the computer: use it only with an isolated workspace. The minimal runtime covers it.
• Limits to know before you build. This protocol has no way to cancel a run or to close a single session, and the client and the runtime must be the same version. The messages, fields and error codes are on The Oda SDK wire protocol; the serving side is on Running an Oda runtime server.

Serve an automation client

The automation profile (acp) serves a client that speaks the Agent Client Protocol. One process serves one client, runs until the client disconnects, and keeps standard output for protocol messages only.

1. Initialize the connection.
2. Create a session; give it an absolute working folder, so both sides agree on where the work happens. When the session needs the tools of other services, declare MCP servers, local or over HTTP; Memory, skills and connectors covers how they work in Oda.
3. Choose the model for the session, and a reasoning effort where the model offers one, from the options the connection advertises.
4. Send prompts, and read the session's updates while the session works.
5. Close the session with session/close when you are done. Another process can list and resume the same stored sessions later; a resume reconnects the MCP servers its request declares and does not replay the earlier conversation.

• Closing standard input shuts the process down cleanly.

• Access is asked per request. A permission request offers Allow once or Reject. Both are one-shot, and a request your client does not answer is settled as cancelled with nothing granted.

• A running prompt can be cancelled; it settles as cancelled. With nothing in flight, the same call cancels autonomous work.

• Every prompt settles with a reason. A completed run ends as end_turn, a cancelled run as cancelled, and a run cut off at its token limit as max_tokens.

• The full call set, the refusals and the limits are on Oda as an automation server (ACP); the rules every serving mode follows are below.

Rules of the serving modes

• --help starts no server. The --help flag prints a profile's help and exits, and leaves standard input and output untouched.
• One client per process. A serving runtime works with one client, and runs until that client disconnects. Give each client its own process.
• Only the advertised surface. A serving mode adds no private methods or fields; clients use only what its protocol advertises.
• Standard output is for the protocol. The stream carries only protocol messages, and your client reads every byte of it. Keep anything else off it: a patch or plugin that prints there breaks the connection. Write your own output to a file, or log on the client's side.
• Configuration changes need a restart. A running connection never observes a replaced server; stop the process, change the configuration, and start it again.

The minimal runtime

The minimal runtime (sdk-minimal) is a small standalone runtime, meant for an SDK client that needs exactly that: one model adapter and a single tool, a persistent shell (bash on macOS and Linux, pwsh on Windows). It deliberately leaves out the shared services of the other modes: there are no settings pages, no managed credentials, no telemetry, no compaction, no filesystem tools, no workspace instructions, no skills, no jobs and no sub-agents. It stores sessions as plain JSON lines under the Oda home folder.

• The model comes only from the client's initialisation request, which overrides environment defaults.
• The context window falls back to about 1,000,000 tokens, and a launch setting changes it.
• The system prompt is a short coding-assistant persona by default, and a launch setting replaces it.

Settings for SDK deployments

• Token-limit stops. A deployment setting decides whether a run that stops at its token limit counts as accepted or as an error.
• Bundled Python runtime. The SDK profile ships a bundled Python runtime for its Office document features. A deployment setting replaces it; setting it to an empty value turns the bundled runtime features off.

Deliveries that start work

A verified GitHub delivery can open a chat by itself, through the rules you set up. The chat is an ordinary chat in the folder the rule names; nothing is queued or retried behind a delivery. Webhook sessions covers what a delivery creates and its limits.

Questions, answered

Which way should I automate Oda?

Match the entry point to what you already have. For one task from a terminal or a script, use a one-off run. For a program that should drive chats itself, use the Oda SDK. For a tool that already speaks the Agent Client Protocol, use the automation profile. All of them run Oda as its own process, and none needs the app window.

Which modes does Oda ship for automation?

One-off runs (the headless mode), the SDK profile (sdk) with its small standalone sibling (sdk-minimal), and the automation profile (acp) for Agent Client Protocol clients. The profiles and how they are started are on DataMind Oda on the command line.

Do I need to set up a model before an automated run works?

Yes. Oda needs a model credential: sign in to your DataMind server, or provide a key through Settings > Models (Set up models and providers). Until a credential resolves, model requests fail.

Can one automation process serve several clients?

No. A serving mode works with one client per process, and it runs until that client disconnects; give each client its own process. The same holds for an SDK runtime.

Which models and effort choices does an automation client get?

The options the connection advertises: the model selector lists the routes the deployment keeps visible, and a reasoning effort selector appears when the model declares reasoning levels. Oda as an automation server (ACP) covers how a change applies.

What happens if my client does not answer a permission request?

The request settles as cancelled and nothing is granted; an unknown choice never grants access either, and a failure on the client's side fails closed. The next request asks again, because no decision is remembered.

Is the minimal runtime safe to point at a folder I care about?

No. It runs with full access, with no sandbox limits and no approval prompts, so its shell can change any path the process can reach. Use it only with an isolated workspace.

Can I change the configuration while a client is connected?

No. A running connection never observes a replaced server, so configuration changes need a restart: stop the process, change the configuration, and start it again.

What happens to a session when the client disconnects?

Closing standard input shuts the process down cleanly. The sessions are kept, and another process can list and resume them; a resume reconnects the MCP servers its request declares and does not replay the earlier conversation.

What can an integration not do?

The Oda SDK protocol has no cancel and no per-session close, and an automation client cannot fork or delete sessions. Standard output must carry only protocol messages in every serving mode. Each linked page lists its own limits and unsupported surfaces.

How can I follow an automated run while it works?

A one-off run streams its working notes to standard error, and it can emit a JSON event stream instead of the final answer. An SDK client reads session.event notifications and the running and idle statuses. An automation client receives session/update messages while the session works. The linked pages list each event vocabulary.