Your project

Three mechanisms together make a project work under kapsl, and they live at different levels of trust:

  1. Project configuration — a .kapslrc (YAML) at the project root, committed with the code. It grants things to the tools the project names: a default environment file, extra capabilities, published ports for the server subcommand, credentials for the publish subcommand. It is read from the directory you run in, and it is trust-gated: on first use you see exactly what it declares and decide.
  2. Tool mappings — the [tools] section of your own ~/.config/kapsl/kapsl.toml. This is where a tool name means an image: your local overrides, dotfiles, capability defaults, aliases, and groups. Only you can change it; no project file touches it.
  3. Shims — symlinks in ~/.local/bin that make the tools feel native: python, node, cargo on your PATH, dispatching through kapsl by argv[0].

The one rule that ties them together: a project grants, it never redefines. A .kapslrc can add capabilities, ports, env, and dotfiles to a tool — it cannot say which image the tool is, which binary it runs, or what a name means. Those are decisions in your own config or the signed catalogue, and a cloned repository cannot move them. An alias in a project file mints a new name; it can never shadow an existing one, because a real tool wins any collision. That is what makes git clone some-repo && cd some-repo && kapsl python safe: the repository can ask for more, but only a human says yes, and only to the grants.

Pages in this section

  • Project configuration .kapslrc: the grants-only project overlay, field by field, with the trust prompt end to end
  • Tool mappings Your [tools] section: what a name means — images, dotfiles, env, aliases, groups, resolution order, and [enforce]
  • Shims --install/--list, argv[0] dispatch, KAPSL_ARGS, and completions