Getting started with open-source Kortix: open the manifest before you prompt
Four commands take an empty directory to a running open-source Kortix workspace, and the kortix.yaml manifest and agent grants to read before your first prompt.
Four commands take an empty directory to a running open-source Kortix workspace, and the kortix.yaml manifest and agent grants to read before your first prompt.
Canonical: https://kortix.com/blog/getting-started-with-kortix
Kortix is the open-source CompanyOS. Four commands take an empty directory to a running workspace, starting with the
kortix.yamlmanifest you own.
Canonical: https://kortix.com/blog/getting-started-with-kortix
Four commands take an empty directory to a workspace running on Kortix: install the CLI, sign in, scaffold, ship. Kortix ships as open source, and what kortix init leaves on your disk is a git repository you own. Before the first prompt, open kortix.yaml. The starter agent's grants are in it, and reading them takes a minute.
What lands in your workspace
kortix init writes the platform onto your disk: a kortix.yaml manifest, starter agents, and the configuration that reads them (Kortix on GitHub). That repository is the CompanyOS written down: the manifest, the agent prompts, the skill folders, the memory file and the connector settings, side by side and all editable. The agents run on cloud computers the platform starts for each session. Edit a line and the company changes by that one diff; revert it and the change is gone (Kortix docs).
The manifest comes from a base template with a skills layer on top, and kortix init fills the skills registry from what that layer ships. Comments removed, this is what kortix init my-agent writes (starter template):
project:
name: "my-agent"
description: A Kortix workspace.
builtin_agents:
my_kortix: true
default_agent: mykortix
skills:
agent-browser: skills/agent-browser
convert-documents-to-markdown: skills/convert-documents-to-markdown
design-foundations: skills/design-foundations
docx: skills/docx
pdf: skills/pdf
presentations: skills/presentations
web-publishing-and-deployments: skills/web-publishing-and-deployments
webapp: skills/webapp
website-building: skills/website-building
xlsx: skills/xlsx
agents:
worker:
description: "General-purpose worker: coding, research, writing, ops and data work, done end to end in its own sandbox."
mode: primary
permission: allow
prompt_file: agents/worker.md
tools: "*"
skills: "*"
connectors: "*"
secrets: "*"
kortix_permissions: "*"
workspace: { project_repository: true }
Nothing in that file names a schema version, because the manifest format has no version. default_agent decides which agent a session runs when the request names nobody, and the starter points it at mykortix, the built-in agent you talk to. My Kortix hands each task to worker unless you name another agent. prompt_file points at agents/worker.md, which holds the instruction and nothing else; a prompt file has no frontmatter. workspace: { project_repository: true } gives each session a checkout of the repo it works in.
The skills: block is a registry, not a grant list: each name maps to a folder holding a SKILL.md, and the worker's own skills: "*" is what lets it load them. The starter ships ten of those folders. An eleventh, skills/kortix-cli, stays out of the registry because the Kortix skills are always registered without being listed (kortix.yaml reference).
The agents.worker block is the grant list, and it is where a new workspace starts widest. tools, skills, connectors, secrets and kortix_permissions all say *, which means every name. The worker may call every registered tool, load every skill, reach every connector. It reads every secret shared with the workspace, and acts on every permission the workspace holds. The starter is built to work before you narrow anything. Narrowing is one line. Leave a grant out and that category resolves to nothing, so replacing connectors: * with the two slugs the worker needs removes the rest in the same diff (kortix.yaml reference). Three keys stay open without a grant: tools is *, permission is allow, and codemode is on.
Install the CLI and scaffold
The installer handles macOS and Linux, both arm64 and x86_64; on Windows, use WSL (Kortix docs). Then kortix login, kortix init and kortix ship take over.
curl -fsSL https://kortix.com/install | bash
kortix login
kortix init my-agent
cd my-agent
kortix ship
kortix init creates the directory from the starter and runs git init -b main. It then asks which local coding tool to wire up. The manifest it writes carries no version line. A kortix_version: 2 file in an older workspace is converted, not dropped: kortix validate reports one warning with fix: legacy-format and then validates the converted file, and kortix validate --fix writes the conversion for good (Older formats). kortix_version: 3 is dropped with a warning, versions 1 (kortix.toml) and 2 are converted with one, and any other value is an error (manifest schema). kortix ship validates kortix.yaml, commits your changes, offers to set a missing secret, and pushes the branch. In a directory with no link and no default workspace, that first push creates the workspace. Prefer the browser? Create a workspace at Kortix and start a session with nothing installed.
Start a session with a prompt
Give a session a job with --prompt, then read the change requests it has opened:
kortix sessions new --prompt "Summarize this week's commits and open a change request"
kortix cr ls
The first command boots a sandbox and runs the default agent on your prompt; --agent and --model override either. The second lists the change requests sessions have opened (Kortix docs). Each session gets a branch of its own, named for the session ID, inside an isolated sandbox. Two sessions on one workspace do not collide. Start one from a browser, a Slack thread, a terminal or the API, and it hands back finished work when it ends.
Review the change request
The agent opens the change request itself once the session has commits on its branch. If it has not, ask it to, or run kortix cr open with the session ID. You read the diff, then merge it or send it back (Kortix docs). Session work reaches main through a change request. Merge is default-deny for agents. From the CLI, kortix cr diff 1 prints the unified patch and kortix cr merge 1 merges into the default branch (Kortix CLI docs).
Self-host it or use managed cloud
Run it on Kortix Cloud, in your VPC, or on your own on-prem network. Self-host is free. Bring up an instance on a host you control with kortix self-host start. It needs two keys, one for Platinum and one from a model provider; without the Platinum key, sessions do not start. The instance also needs a public address, because the sandboxes it starts call home (Self-hosting). Sessions run in Platinum sandboxes rather than on the instance host. kortix hosts use selfhost points the CLI at your instance, kortix hosts use cloud switches back, and the commands in between stay the same.
The harness under the agent
Underneath, each session runs an agent harness whose permission rules reach down to a single shell command. Every new session runs pi, an open-source (MIT) agent harness, so the runtime is not what locks you in (Kortix on GitHub). The part you change is above it: the prompt in agents/worker.md and the grants in kortix.yaml, both files your reviewer diffs.
Next reads: Introducing Kortix and Kortix vs Claude Cowork. Start with Kortix and run kortix init.