Role Repositories

What is a role repo?

A role repo is a GitHub repository that defines a specific role. It contains:

1. A Dockerfile — the role's environment definition (tools, languages, SDKs)
2. A manifest file (jackin.role.toml) — metadata about the role

When you run jackin load agent-smith, jackin❯ looks for a GitHub repo named jackin-agent-smith and builds a container from it.

A role repo is where you decide what kind of worker you are creating. In most teams, that means creating role-specific environments rather than one universal image. A frontend-oriented role repo can install browser tooling and UI-focused plugins, while a backend-oriented repo can install server toolchains and database clients.

A role is best thought of as a reusable tool profile. It is where you decide things like:

• which language toolchains are installed
• which helper scripts and shell defaults are present
• which Claude plugins are installed
• whether this is a frontend, backend, infra, or review-focused environment

Naming convention

Role repos follow the jackin-{role-name} naming pattern:

Namespaced roles

Organizations can publish roles under their namespace:

The namespace prefix maps directly to the GitHub organization or user.

When should you create another role?

Create another role when the work needs a meaningfully different environment.

Common reasons include:

• frontend work needs Node, browser tooling, and UI-focused plugins
• backend work needs Rust or Go toolchains, API clients, and database tools
• infra work needs Terraform, cloud CLIs, and deployment helpers
• security review work should have a smaller, audit-focused tool and plugin set
• docs work may need writing or publishing tools without bringing in unrelated build systems

The goal is not to create lots of arbitrary images. The goal is to avoid one kitchen-sink image that exposes every tool and plugin to every task.

Role identity

Roles can declare a display name in their manifest:

[identity]
name = "Agent Smith"

This name appears in jackin❯ TUI and output. When omitted, the role selector name is used instead (e.g., agent-smith).

Caching

jackin❯ caches each role's repository on first load and reuses the cached checkout on every subsequent load — there is no manual cache to manage. Branches loaded with --role-branch are cached separately from the default branch, so you can flip between them without re-cloning either side. jackin❯ updates the cache on each load to keep it in sync with the configured source.

jackin❯ is intentionally strict about that cache:

• if the cached repo's origin no longer matches the configured source, load fails
• if the cached repo contains local changes or extra files, load fails

This avoids silently building from a tampered or stale cache. If you intentionally need a clean cache, run jackin purge <role> to drop it and let the next load clone fresh.

The repo contract

Every role repo must satisfy a contract:

1. Must contain jackin.role.toml at the repository root
2. Must contain a Dockerfile at the path declared in the manifest
3. The Dockerfile path must be relative and must stay inside the repo checkout (no ../ escapes)
4. The final Dockerfile stage must use the construct base:

   FROM projectjackin/construct:0.4-trixie

   An optional alias is allowed:

   FROM projectjackin/construct:0.4-trixie AS runtime

5. Earlier stages may use any base image — multi-stage builds are fully supported
6. No symlinks — the derived build-context generator currently rejects symlinks

Example role repo

A minimal role repo for a Node.js development agent:

version = "v1alpha4"
dockerfile = "Dockerfile"

[claude]
plugins = []

[identity]
name = "Frontend Engineer"

FROM projectjackin/construct:0.4-trixie

# Install Node.js via mise
RUN mise install node@22 && mise use --global node@22

# Install common global packages
RUN npm install -g typescript tsx prettier eslint

That's it. jackin❯ handles the rest — agent runtime resolution and installation, entrypoint, user mapping, state persistence, and DinD setup.