---
title: "Kodema quickstart: install and run a pipeline"
description: "Install kodema and kodactl with one command, start a local Kodema on Podman, run a first pipeline, approve a request, start a task and connect an MCP client."
canonical_url: https://optimi.com/en/docs/kodema/getting-started
md_url: https://optimi.com/en/docs/kodema/getting-started.md
language: en
alternates:
  - lang: fr
    url: https://optimi.com/fr/docs/kodema/premiers-pas
    md_url: https://optimi.com/fr/docs/kodema/premiers-pas.md
last_updated: 2026-11-14
---

# Quickstart

`kodema up` starts a complete Kodema on one machine, and `kodactl run` runs a
pipeline file on it. This is the shortest way to try Kodema 0.2.1.

It is **not a production installation**: one host, a local keyfile, and a
built-in sign-in that asks for no password. For production, read
**[Operations](/en/docs/kodema/operations)**.

## Before you start

- **Linux with rootless Podman 5 or newer** and its user API socket:
  `systemctl --user enable --now podman.socket`, and `podman info` succeeds.
- **`curl` and `tar`**, for the installer.
- **Port 8443 free.**

Docker is not supported, because Kodema starts workloads through the Podman
API. macOS with a Podman machine is expected to work and has not been run.

## Install and start

```sh
curl -fsSL https://raw.githubusercontent.com/optimiware/kodema/master/install.sh | sh
kodema up
source ~/.kodema/instances/default/env.sh
kodactl whoami
```

The installer puts `kodema` and `kodactl` into `~/.local/bin`, which must be on
your `PATH`. It downloads the two archives of the latest release for your
operating system and architecture, and installs nothing unless both match the
release’s `SHA256SUMS`. Run it again to upgrade.

| Installer variable | Effect |
| --- | --- |
| `KODEMA_VERSION` | Install another release (0.2.1 or newer) instead of the latest |
| `KODEMA_INSTALL_DIR` | Install into another directory than `~/.local/bin` |

`kodema up` pulls the container image of its own version and is safe to run
again. It:

1. Starts PostgreSQL, NATS, the Kodema server and the Git service as
   containers, and a gateway on `https://127.0.0.1:8443` that serves the API,
   MCP (`/mcp`), sign-in (`/auth/`) and Git (`/git/`).
2. Creates a local CA and certificates, the tenant `tenant-local` and the
   project `project-local`.
3. Gives the four built-in personas their project roles: `admin` (every role),
   `engineer`, `reviewer` and `operator`.
4. Writes `env.sh`, which points `kodactl` at this installation as `admin`.

Everything is kept in `~/.kodema/instances/default`. `kodactl whoami` should
answer with the roles `admin,engineer,reviewer,operator`.

## Run your first pipeline

The local runtime never pulls an image. Pull the one the pipeline names, and
name it by digest:

```sh
podman pull docker.io/library/alpine:3.24@sha256:0f49f331d9212aff11b932863be4eb01cdf962969aa86dab7d1ee21ac6f5f52b

cat > hello.yaml <<'EOF'
actions:
  - name: hello
    image: docker.io/library/alpine@sha256:0f49f331d9212aff11b932863be4eb01cdf962969aa86dab7d1ee21ac6f5f52b
    timeout: 2m
    commands:
      - echo "hello from a Kodema workload"
EOF

kodactl run hello.yaml
```

```text
execution execution-… started
hello from a Kodema workload
execution execution-… succeeded
```

`kodactl run` starts the file, waits for the execution to end and prints the
output of its actions. It exits 0 when the execution succeeded and 1 when it
failed, with the reason the server reports. The output appears when the
execution ends, not while it runs. Nothing is stored: the YAML is sent inline.

## Ask for an approval

An action can ask a role for a decision instead of running a container:

```sh
cat > review.yaml <<'EOF'
actions:
  - name: prepare
    image: docker.io/library/alpine@sha256:0f49f331d9212aff11b932863be4eb01cdf962969aa86dab7d1ee21ac6f5f52b
    timeout: 2m
    commands:
      - echo prepared
  - name: review
    request: role/reviewer
    subject:
      operation: local.approve
      resource: local-demo
    timeout: 10m
EOF

kodactl run review.yaml
```

`run` stops when the execution waits for a person, and names the execution.
Answer it from the inbox:

```sh
kodactl inbox
kodactl approve <execution-id>      # or: kodactl reject <execution-id> --reason "…"
kodactl watch <execution-id>
kodactl logs <execution-id> --action prepare
```

No container runs while the request waits. After a pass, the execution
continues with its next action in the same workspace; a rejection or a timeout
fails it.

## Store a pipeline and start it from a task

To keep a pipeline in the project and start it from a task:

```sh
kodactl pipeline apply hello.yaml          # prints the pipeline id
kodactl task run --title "First task" --pipeline <pipeline-id>
kodactl task list
```

A task keeps a title, a conversation and the history of its executions. It is
`done` when its current execution succeeds.

## Sign in as a person

`env.sh` uses an administrator token that `kodema up` wrote. To act as one of
the personas, sign in:

```sh
unset KODEMA_CREDENTIAL_FILE
kodactl login            # or: kodactl login --device, without a browser
kodactl whoami
```

The sign-in page offers the four personas and asks for no password. It answers
this machine only.

Project and membership administration needs the tenant-wide administrator
token instead:

```sh
kodactl --credential-file "$KODEMA_TENANT_ADMIN_CREDENTIAL_FILE" member list
```

## Use Git

The tenant’s admin repository is served under `/git/`. Authenticate with a
credential-store file, never an argument:

```sh
creds=~/.kodema/instances/default/git-credentials
(
  umask 077
  printf 'protocol=https\nhost=127.0.0.1:8443\nusername=kodema\npassword=%s\n\n' \
    "$(cat ~/.kodema/instances/default/admin-token)" |
    git credential-store --file "$creds" store
)
git -c http.sslCAInfo="$KODEMA_CA_FILE" -c credential.helper="store --file=$creds" \
  clone https://127.0.0.1:8443/git/admin
```

The admin repository holds `conf/git.conf`, the access rules of every
repository of the tenant. **[Concepts](/en/docs/kodema/concepts)** explains
them.

## Connect an MCP client

```sh
kodactl mcp install claude --print     # or cursor, codex; without --print it writes the client’s config
```

The client then sees every Kodema operation as a tool. See
**[API and MCP](/en/docs/kodema/api)**.

## Operate the local installation

```sh
kodema status
kodema up              # again: renews the credentials below
kodema down            # stops it and keeps the state
kodema down --purge    # removes the containers, volumes and state
```

- The administrator token in `env.sh` lasts 24 hours and the Git service
  credential 8 hours. Run `kodema up` again to renew both.
- `kodema up --name <name>` runs a second installation; give it another
  `--listen` port.

## Other ways to install

**Without the script.** Download the `kodema` and `kodactl` archives for your
system and `SHA256SUMS` from the
[latest release](https://github.com/optimiware/kodema/releases/latest), then:

```sh
sha256sum --check --ignore-missing SHA256SUMS    # macOS: shasum -a 256 --check --ignore-missing SHA256SUMS
tar -xzf kodema_*.tar.gz && tar -xzf kodactl_*.tar.gz
install -m 0755 kodema_*/kodema kodactl_*/kodactl ~/.local/bin/
```

**From a checkout.** With Go (the version in `.go-version`), `git` and `make`:

```sh
git clone https://github.com/optimiware/kodema && cd kodema
make build image
bin/kodema up
source ~/.kodema/instances/default/env.sh
```

`make build` builds `bin/kodema` and `bin/kodactl`. `make image` builds the
container image of the same version, which is the image `kodema up` starts.

## Troubleshooting

| Symptom | What to check |
| --- | --- |
| `kodema: command not found` after the installer | `~/.local/bin` is not on your `PATH` |
| `kodema up` refuses the container engine | It needs Podman and refuses a Docker engine. Check `podman info` and the user socket |
| `kodema up` cannot listen | Port 8443 is taken. Free it, or start with another `--listen` address |
| The execution fails as soon as it starts, naming an image | The image is missing from the local Podman store. `podman pull` it, by digest |
| A command is read as a mapping | A command that contains `: ` must be quoted in YAML |
| `kodactl` answers `unauthenticated` after a day | The administrator token expired. Run `kodema up` again, then `source` `env.sh` |
| `kodactl run` exits 1 without a failure | The execution waits at a request. Use `kodactl inbox` and `kodactl approve` |
| No output while a long action runs | `kodactl run` prints a workload’s output when the execution ends |

## Limits of this installation

- One host, one tenant, a local keyfile. Anyone who can use this machine can
  sign in as any persona.
- On Linux the gateway listens on every address, because containers reach the
  host on its outward address. It refuses every peer that is not this machine,
  so the installation is not reachable from another host.
- Podman only, and `kodema up` has run on Linux only.
- The [Podman bundle](https://github.com/optimiware/kodema/blob/master/docs/runbooks/podman-quickstart.md)
  is a second single-host installation, with a separate identity provider. The
  release smoke test runs on it.

Next: **[Concepts](/en/docs/kodema/concepts)**, then
**[Writing pipelines](/en/docs/kodema/developer-guide)**.
