Kumoss
prerelease Prerelease stable Latest
↑↓ navigate · ↵ select · esc close
Kumoss
Kumoss
prerelease Prerelease stable Latest

Quickstart

Install Kumoss on one machine with Docker Compose, from cloning the repository to opening the running web application.

In this quickstart, you install Kumoss on one machine with Docker Compose, using the bundled stack as shipped, and open the running web application.

Prerequisites

Before you begin, make sure you meet the prerequisites.

Step by step

1. Clone the repository and create the environment files

git clone https://github.com/InditexTech/kumoss.git
cd kumoss

cp core/env.sample core/.env
cp services/iac/env.sample services/iac/.env

Each env.sample documents its own variables and is the source of truth for their names. Every .env file is gitignored; never commit one.

2. Write config.yaml

config.yaml at the repository root is the single configuration file. It is baked into the core image at build time, so every edit needs docker compose build core.

What to Edit vs. Keep as Default

  • Must Modify / Verify:

    • llm.model: set your primary LLM provider model string.

    • llm.small_model: set your lightweight model string.

The llm values below are only an example: replace both model strings with the models you prefer. Model strings per provider: LLM providers and models.

llm:
  model: "vertex_ai/claude-sonnet-5-5"
  small_model: "vertex_ai/gemini-3.8-flash"

  • Optional / Conditional:

    • git.provider: only modify if you are using GitLab ("GITLAB") or Azure DevOps ("AZURE_DEVOPS"). Defaults to "GITHUB". Accepted values and the supported hosts: git configuration.

git:
  provider: "GITHUB"  # or "AZURE_DEVOPS", "GITLAB"

  • Keep as Default:

    • All unmentioned configuration fields automatically fall back to core code defaults.

3. Fill in core/.env

The core/.env passes mandatory runtime secrets such as LLM API keys and Git access tokens. The core will not run without them.

every .env file is gitignored by default. Never commit a .env file containing real credentials to version control.

What to Edit vs. Keep as Default

  • Variables you MUST set:

    • LLM provider credentials: set the specific API key or authentication variables required by LiteLLM for the provider prefixes configured in llm.model and llm.small_model. See examples below. For more info see provider credential variables.

    • GIT_USER, GIT_TOKEN: the account username and personal access token for the provider named by git.provider defined in config.yaml. See examples below.

  • Variables to Keep as Default:

    • All other sample values in core/env.sample: leave all pre-populated values intact (such as internal tokens, container URLs, and service connection details). These are pre-configured to match the bundled Docker Compose setup. For a complete reference of every variable, see environment variables and secrets.

if you modify core/.env after the stack is already running, recreate the container using docker compose up -d core to apply changes. Running docker compose restart will not reload .env variables.

Brief core/.env examples

Anthropic example:

ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxxxxxxxxxxxxx"

Google Vertex AI example::

VERTEXAI_PROJECT="your-gcp-project-id"
VERTEXAI_LOCATION="us-central1"
VERTEXAI_CREDENTIALS='{"type": "service_account", "project_id": "my-project", ...}'

Azure OpenAI example:

AZURE_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
AZURE_API_BASE="https://your-resource.openai.azure.com"
AZURE_API_VERSION="2025-01-01-preview"

Git Credentials example:

GIT_USER="your-git-username"
GIT_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxxxxxx"

4. Fill in services/iac/.env

The services/iac/.env file passes your cloud provider access keys and execution engine settings directly to the IaC sidecar.

missing or invalid cloud credentials in services/iac/.env do not stop the container. The engine runs anyway, but authentication errors will appear inside the session as a failed init, plan, or apply operation.

What to Edit vs. Keep as Default

  • Variables you MUST set:

    • Cloud provider credentials: set the specific authentication variables required by your OpenTofu or Terraform providers. See terraform providers for the minimum set per cloud and authentication method.

  • Optional / Conditional Settings:

    • IAC_BINARY: the sidecar runs OpenTofu 1.12.6 by default. Set IAC_BINARY=terraform only if you explicitly want to use the bundled HashiCorp Terraform 1.16.0 instead (selecting Terraform makes your use subject to its BUSL-1.1 license).

  • Variables to Keep as Default:

    • Internal service settings (e.g., KUMOSS_IAC_TOKEN): leave these pre-populated values intact so they remain synchronized with core/.env and the container stack.

recreate the sidecar using docker compose up -d iac whenever you update services/iac/.env.

Brief services/iac/.env examples

AWS Credentials Example:

AWS_ACCESS_KEY_ID="AKIAXXXXXXXXXXXXXXXX"
AWS_SECRET_ACCESS_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
AWS_REGION="us-east-1"

GCP Credentials Example:

GOOGLE_CREDENTIALS='{"type": "service_account", "project_id": "my-project", ...}'

Azure Credentials Example:

ARM_CLIENT_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
ARM_CLIENT_SECRET="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
ARM_TENANT_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

5. Build and start Kumoss

docker compose up --build

Add -d to run in the background. The first build downloads the base images, installs the Python dependencies, downloads both IaC engines, and compiles the web application.

After a later change to config.yaml, rebuild and restart the core:

docker compose build core
docker compose up -d core

A change to a .env file needs the affected container recreated (docker compose up -d core, docker compose up -d iac); docker compose restart does not reload it.

6. Verify the services

docker compose ps
docker compose logs -f core

Wait for Application startup complete in the core log. Boot is strict: if a start-up step fails, the container exits with the reason in the log. A notifications container that has exited is expected while that optional sidecar is unconfigured.

curl http://localhost/api/v1/auth/config

With authentication disabled this returns a JSON document with an empty issuer_url.

Where Terraform state lives

By default, Kumoss keeps Terraform state in the bundled RustFS object storage, in the kumoss-terraform-state bucket. Each project (repository, cloud scope, and root-module path) gets its own state file, which starts empty the first time Kumoss works on it. Any backend block in the repository is ignored.

To use your own external state instead, new or already existing, in AWS S3, Azure Storage, or Google Cloud Storage, see Configure state backends.

See it working

URL What it serves

http://localhost

Kumoss web application and the API under /api/v1/…​

http://localhost/monitoring/

Phoenix: traces of every run and the prompt registry

Port 80 serves the unauthenticated Kumoss application by default, while port 9000 exposes presigned artifact downloads, on every interface of the host. Keep the stack on a machine only you can reach. The RustFS web console is disabled; to enable it, see RustFS console.

Use a test repository and a sandbox cloud scope for this first run. Because every project starts with empty state, a repository whose infrastructure already exists gets a plan that creates it all again.

Open http://localhost. With authentication disabled you land directly in the wizard as the local developer. Enter a repository your Git token can push to, choose the cloud and scope, describe the infrastructure you need, and follow the session. What each mode does is explained in Guides; your sessions and the admin panel are described in Administer users and locks.

Open http://localhost/monitoring/ to see the traces of the run and the seeded prompts under Prompts. Phoenix receives prompts, plans, and generated code in clear text and has no authentication of its own in this stack; see Monitor with Phoenix.

Stop or reset the stack

docker compose down            # stop; named volumes are kept
docker compose down -v         # stop and delete all volumes

down keeps the databases, artifacts, and workspaces, so sessions and prompts survive a restart.

down -v deletes the session database, the artifacts, the Phoenix traces and prompts, any in-progress workspaces, and the Terraform state kept in RustFS.

Next steps

Troubleshooting

  • The core exits during boot. Boot is strict and the reason is in docker compose logs core — most often missing LLM credentials, an empty KUMOSS_IAC_TOKEN or database URL in core/.env, or Phoenix not yet reachable. The stack has no healthchecks, so a dependency that was simply slower to start leaves the core stopped rather than retrying: run docker compose up -d core again.

  • Every session fails at validation with a 401 from the IaC sidecar. KUMOSS_IAC_TOKEN differs between core/.env and services/iac/.env.

  • A config.yaml change has no effect. Rebuild the core image with docker compose build core.

  • plan or apply fails with a provider authentication error. The cloud credentials in services/iac/.env are absent, invalid, or insufficient.

  • plan fails with permission denied on a file in the workspace. The workspaces volume predates the current non-root containers. Run docker compose down, then docker run --rm -v kumoss_workspaces:/workspaces alpine chown -R 10001:10001 /workspaces, and start again.

  • init fails on the state backend, or every plan wants to recreate existing resources. Troubleshooting state backends.

  • Push or pull-request creation fails. Check GIT_USER, GIT_TOKEN, that git.provider matches the repository host, and the token’s permissions.

  • A session aborts because a prompt is missing. The prompt is absent from Phoenix or has no version tagged with the environment value. See Customize prompts.

  • The browser cannot download an artifact. Port 9000 must be reachable from the browser under the host in storage.public_endpoint_url.

  • LLM calls fail although the core booted. Not every provider can be validated at boot. See LiteLLM troubleshooting.