Agents

An agent is a markdown file that defines how OpenCode acts in a session. This page covers agent files, skills, and how a session picks an agent.

OpenCode runs every session

OpenCode, the open-source coding-agent runtime, runs every session. The kortix-agent daemon starts it as opencode serve, with its config directory pointed at the project's .kortix/opencode/ folder.

An agent is two files

Each agent has two parts:

• Behavior — a markdown file at .kortix/opencode/agents/<name>.md. Its frontmatter sets the model, mode, and tools. Its body is the system prompt.
• Governance — an entry in kortix.yaml's agents map, keyed by the same name. It sets what the agent may access on Machine: secrets, skills, and CLI actions.

The manifest never sets a prompt, mode, or tool. The .md file never sets platform access. See the manifest reference for every governance field.

Governance is mostly deny-by-default

An agent with no secrets, skills, or kortix_cli key gets none of that access. Set a field to all to grant full access, or list specific names. default_agent in kortix.yaml names the agent a session starts when you request no agent.

Two kinds of access are project-wide and ignore the agent's lists:

• Connectors. Every agent can call every connector connected on the project. An agent's connectors list no longer narrows this. Each connector's approval policies still apply, and a session for an agent with connectors_required still fails to start until the connectors it names are connected.
• Sandbox secrets. Every agent receives every secret whose delivery is Sandbox. The secrets list gates only Network boundary and Machine service delivery. See Secrets.

Legacy kortix.toml (v1) projects list agents in an array, not a map. In v1 an omitted env (the v1 name for secrets) means all, but all never delivers a Network boundary or Machine service secret: those always need the identifier listed by name. An omitted kortix_cli means none, as in v2. See Legacy TOML and the manifest reference.

Skills give an agent know-how

A skill is a markdown file at .kortix/opencode/skills/<name>/SKILL.md. OpenCode loads a skill on demand when the agent calls it — Machine does not inject skills into every prompt. An agent's skills grant in kortix.yaml controls which skills it may load.

How a session picks its agent

Creating a session accepts an agent_name. Machine starts that agent for the session. If you omit agent_name, Machine uses the project's default_agent. Set the default agent from the dashboard, the API, or the SDK. Each writes default_agent to kortix.yaml and commits the change to the project's default branch.

An agent never exceeds the access of the person or token that started the session.

New or changed agents and skills reach future sessions only after a change request merges them into the default branch. Connect external tools before an agent can use them; see Connectors.