# The goal's repository Every goal is a private git repository. What lives in it, how changes land in it, and the machines work runs on. Canonical page: https://app.auto-lab.ai/docs/developers/repository Every goal is backed by a private git repository that holds its instructions, memory, plan, agents, skills and settings as files, so every change has an author and a history and can be reviewed or undone. You never need to open it to use Auto Lab. This page is for developers who want to read it, clone it or change it by hand. ## Where the repository lives You choose where the repository lives when you create the goal. **Auto Lab managed** is the default. The GitHub options sit behind **Have code already? Import a GitHub repository** on the Describe page. | Option | What happens | |---|---| | **Auto Lab managed** | Auto Lab creates and manages a private repository for the goal. Its default branch is `main`. | | **Create in GitHub** | Auto Lab creates a private repository in a GitHub account connected to your organization. | | **Import from GitHub** | You pick an existing repository from that GitHub account. | The two GitHub options need a GitHub account connected to the organization first. ### Keep it small The goal's repository holds what the agents know and the rules they work under. It is not where your product lives. Every session clones it, so keep it small. Your product code stays in its own repositories. When a task needs to change one, a coder task clones that repository in its session and works there. Do not add a manifest to an existing codebase to turn it into a goal. Create a goal, and tell it which repositories it works on. ## Settings › Git repo **Settings › Git repo** shows the repository the goal runs from. | Row | What it shows | |---|---| | **Repository** | The repository, with a link to it on GitHub when it lives there. | | **Status** | **Connected**, **Needs attention**, **Connecting…** or **Not connected**. A banner explains a repository Auto Lab can't reach. | | **Base branch** | The branch new sessions and change requests start from. | | **Manifest file** | The path of the [goal manifest](/docs/developers/manifest), `kortix.yaml` by default. | ### Clone it with the CLI **Work on this locally** lists the commands. Install the CLI first, see [CLI](/docs/developers/cli). The CLI calls a goal a project. ```bash kortix projects clone cd kortix init --force kortix env pull ``` - `kortix projects clone` clones through Auto Lab with your CLI sign-in. No token is written into the remote URL. - `kortix init --force` connects the coding tools you use locally (OpenCode, Claude Code, Codex, Pi or Cursor) to the clone. It does not replace repository files. - `kortix env pull` writes a `.env` file with the names of the goal's secrets and empty values. Secret values never leave Auto Lab, so you fill them in yourself. ### Clone it with plain git Open **Use your own Git client** to copy the clone address. It looks like `https://api.auto-lab.ai/v1/git/.git`. When git asks for credentials, enter any username and a personal access key as the password. You create keys in **Personal settings › Personal access keys**, see [API and sign-in](/docs/developers/api). A push with your key acts as you. If your role lets you push, you can push to any branch, including the default one. Prefer a branch and a change request, so your change is reviewed like the agent's. Deleting a branch needs the goal admin role, and nobody can delete the default branch. ### Give someone direct access People who can manage the goal's members also see **People with access**. For an Auto Lab managed repository, invite a GitHub username with **Can edit** or **Can view**, and GitHub emails them an invitation. For a repository in your own GitHub account, manage access on GitHub with **Manage on GitHub**. ## What lives in the repository The UI calls `kortix.yaml` the project manifest and `.kortix/` the system files. ```text kortix.yaml the goal manifest .kortix/ memory/ what the goal knows objective.md the objective, in full instructions.md goal instructions a person approved profile.md a one-page profile, rewritten each night playbook.md the lessons that matter most, ranked each night knowledge/ facts, procedures, preferences, decisions, lessons entities/ people and organizations timeline/ notes from each turn, rolled up by day, week and month comms/ the text of messages sent and received, by channel workstreams/ active, completed and someday work plan/ PLAN.md this week's plan tasks.yaml its tasks, owners and check-ups opencode/ agents/.md an agent's prompt and behaviour skills//SKILL.md a skill; learned-/ folders are ones learning wrote opencode.jsonc settings for the agent runtime in sessions Dockerfile optional, a custom machine image ``` A few files need a word more: - **Goal instructions.** `instructions.md` is a short list of standing instructions. The agent reads it on every turn, right after its own prompt. Learning can propose one small edit at a time, always as a change request. You can edit it yourself in **Brain › Memory**. - **The plan.** Launch approves `PLAN.md` and `tasks.yaml` and copies the tasks to the Overview. From then on the Overview's **Work** board is the live state, not the file. - **Agents and skills.** The Chat's own prompt is built in, unless the repository has `.kortix/opencode/agents/harness-main.md`. The Chat and sessions read the same skills. See [Agents and skills](/docs/brain/agents-and-skills). - **Learned items.** Lessons, stated preferences and `learned-` skills are what learning applied on its own. Undo any of them in [Brain › Learning](/docs/brain/learning). ## How changes reach the default branch Changes from Auto Lab reach the default branch in one of three ways. 1. **The Chat commits memory directly.** It writes only its notes, message logs, rollups, lessons, stated preferences, the profile and playbook, and its own `learned-` skills. 2. **Everything else is a change request.** The plan, replacing or removing memory, knowledge the agent inferred, the objective, goal instructions, agents, skills a person wrote, the manifest, and any work done in a session. 3. **Some settings commit the manifest directly.** Triggers, connectors, tool rules and the **Delegation** dial write `kortix.yaml` on the default branch when you save them in the UI. Commits and change requests use a title prefix, so you can tell them apart in the history: | Prefix | Kind | What it carries | |---|---|---| | `plan:` | Change request | `PLAN.md`, `tasks.yaml` and sometimes `objective.md`, on a branch named `autolab/plan--`. **Launch** or **Update plan** merges it. | | `memory:` | Commit | The agent's notes after a turn, message logs and the nightly rollups. | | `memory:` | Change request | Replacing or removing memory, knowledge the agent inferred, or a new objective. | | `harness:` | Change request | Changes to agent prompts, skills or goal instructions. | | `learned:` | Commit | What learning applied on its own. Each item can be undone. | Review branches for `memory:` and `harness:` change requests are named `autolab/review--`. On older session goals, `harness:` change requests also come from the daily reflection. Whether a re-plan waits for you depends on the goal's autonomy, see [Approvals and autonomy](/docs/goals/approvals). ### Change requests from a session A session works on its own branch, named after the session id. When it is done, the agent commits, pushes the branch and opens a change request. A person reviews it in **Needs you** or the Review Center and merges it or asks for changes. A few rules always hold: - A session can push only to its own branch. - Its change request targets the branch the session started from. Only a person can retarget it. - No grant lets a session merge its own change request. Someone else has to. - The merge checks `kortix.yaml`. An invalid manifest blocks the merge. - A merged change reaches new sessions. A running session sees it only after it merges the default branch in. ## Where the work runs The Chat runs on Auto Lab's servers. Conversation, memory, connectors and planning need no machine, and the Chat reads the repository through Auto Lab. It picks up a merged change within about a minute. A machine is started only when work needs a shell or files: - **An environment.** The first time a turn or a task agent needs a shell or files, Auto Lab starts an environment: a machine with the repository checked out on its own branch, a shell, git, Node, Python and a browser. Scheduled routines, docs tasks that build a file and browser tasks all work in one. Later calls reuse it. It stops after an hour without use and starts again from its branch when it is needed. - **A session.** A coder task opens a full session with its own coding agent. It ends in a change request. Older goals without the Chat run all their work in sessions. A session's machine stops about 15 minutes after its last turn ends. An open browser tab does not keep it running. Git is the record that lasts. Work that was committed and pushed survives a stopped machine. ## Sandbox templates A sandbox template is the recipe for the machine a session runs on. **Settings › Sandbox templates** lists the goal's templates and the record of every time Auto Lab built a machine image from one. Every goal starts with the **Auto Lab default**, an Ubuntu image with Auto Lab's tools and the repository checked out at `/workspace`. Most goals need nothing else. Add a template when sessions need tools that the default does not have. ### Add a template Click **New template**. Give it a **Name** and a **Slug**. Under **Image source**, pick **Public image** with a pinned tag (not `latest`), or **Dockerfile** with a path inside the repository. Set **Resources** if you need more than the default: 1 to 32 vCPU, 1 to 128 GiB memory, 1 to 500 GiB disk. Leave **Entrypoint** blank. ### Choose which sessions use it A session uses the first of these that is set: the template picked for that session, its agent's `sandbox` key, the manifest's `sandbox.default`, then the Auto Lab default. `sandbox.default` must name a template declared in the manifest. See [Goal manifest](/docs/developers/manifest). ### Wait for the build Creating or changing a template starts a build of its machine image. The first build can take several minutes. Sessions started in the meantime wait for it; they don't fail. You can also declare templates in `kortix.yaml` under `sandbox.templates`. Each template card shows where it was defined: **Auto Lab platform**, **This dashboard** or `kortix.yaml`. The Chat's environment uses a lighter Auto Lab image. When the manifest sets `sandbox.default` to one of your templates, the environment uses that template instead, so your tools are there too. ### When the image is rebuilt A new template, an edited Dockerfile or a merged change to either starts a new build. The **Build log** has one row per build, with what triggered it. A failed row matters only while a banner at the top says sessions can't start. Then use **Rebuild**, or **Fix with agent** to have an agent look at the error. ### Dockerfile rules Auto Lab adds its own runtime layer on top of your Dockerfile. `kortix validate` checks these rules before you push: | Rule | Why | |---|---| | Base the final stage on Debian or Ubuntu. | The runtime layer installs with `apt-get`. | | Don't `COPY` files from the build context. | Your repository isn't in it. It is cloned to `/workspace` when a session starts. | | Don't use `RUN` heredocs. | Some builders can't read them and the build fails. | | Don't put credentials in the image. | Declare the name under `env` and store the value as a [secret](/docs/connect/secrets). |