---
name: cosa-basics
description: Initialize a COSA workdir, build or fetch Fedora CoreOS images, and launch local QEMU VMs using coreos-assembler
---

# COSA Basics

This skill guides you through the core coreos-assembler (COSA) workflow:
initializing a build directory, obtaining a CoreOS build (either from source
or by fetching a published build), and launching a local QEMU VM.

## Out of scope

Cloud platform image building and uploading (AWS, GCP, Azure, etc.) are not
covered here. Load the **cosa-platforms** skill for those workflows.

## Key documentation references

Do NOT duplicate these docs. Read them at runtime for command details:

| File | What it covers |
|------|----------------|
| `docs/building-fcos.md` | Full build walkthrough, prerequisites, the `cosa()` bash alias |
| `docs/cosa.md` | Command reference overview (all cosa subcommands) |
| `docs/cosa/run.md` | Detailed `cosa run` and QEMU VM options |
| `docs/working.md` | Overrides, customization, advanced usage |
| `docs/devel.md` | Running cosa locally outside a container |
| `src/cmd-init` | `cosa init` source -- all supported flags |
| `src/cmd-buildfetch` | `cosa buildfetch` source -- all supported flags |

## Running COSA

### Container mode (default)

COSA is designed to run inside a container. The container image is:

```
quay.io/coreos-assembler/coreos-assembler
```

Before running any cosa commands, read `docs/building-fcos.md` and extract the
`cosa()` bash alias function defined there. This alias wraps `podman run` with
the necessary privileges, device mounts (`/dev/kvm`, `/dev/fuse`), user
namespace mapping, and volume mounts. The current working directory is mounted
as `/srv/` inside the container.

Set up the alias in the user's shell before running any cosa commands.

### Local mode (for cosa developers)

Developers who have cosa installed locally can run commands directly without
the container wrapper. Read `docs/devel.md` for details on this workflow. The
commands themselves are the same; only the execution environment differs.

## Workflow

### Step 1: Set up a COSA workdir

1. Ask the user for a working directory path. Default to `./fcos` if they
   don't specify one.
2. If the directory does not exist, create it.
3. `cd` into the directory.
4. Set up the `cosa()` bash alias (read it from `docs/building-fcos.md`).
5. Initialize the workdir:

```
cosa init https://github.com/coreos/fedora-coreos-config
```

The user can override the config repo URL. Additional useful flags (read
`src/cmd-init` for the full list):

- `--branch BRANCH` -- use a specific branch of the config repo
- `--variant VARIANT` -- select a build variant
- `--force` -- allow init in a non-empty directory

After init, the directory structure will contain `src/config/` (the cloned
config repo), plus `builds/`, `cache/`, `tmp/`, and `overrides/` directories
that are populated during builds.

### Step 2: Obtain a build

Choose one of the following paths based on what the user wants to do.

#### Option A: Build from source

This builds a fresh CoreOS image from the config repo and RPM sources:

```
cosa build
cosa osbuild qemu
```

`cosa build` creates the bootable OCI container (ostree commit). `cosa osbuild
qemu` derives a QEMU disk image from that container. Both are required before
`cosa run` will work.

Note: `cosa fetch` is a no-op in the current build flow. Package fetching
happens automatically inside `cosa build` via buildah.

#### Option B: Fetch an existing published build

This downloads a previously published build from the Fedora CoreOS build
servers. Use this when you want to test or inspect an existing release without
building from source.

**Default flags:** Include `--artifact qemu --decompress` when the user
needs a local QEMU disk image (e.g. for `cosa run` or QEMU-based kola
tests). The published artifacts are stored compressed on the server;
`--decompress` expands them so the resulting qcow2 can be used directly.

If the user only needs to run tests on a cloud platform where images already
exist (e.g. AMIs in AWS), `--artifact` and `--decompress` are not needed.
A plain `cosa buildfetch -b <build-id>` fetches only a few small metadata
files (including `meta.json`), which contain cloud image references that
kola picks up automatically. See the **cosa-platforms** skill for details.

**Fetch the latest build for a stream:**

```
cosa buildfetch --stream <stream> --artifact qemu --decompress
```

Available streams: `stable`, `testing`, `testing-devel`, `next`, `rawhide`

If the user does not specify a stream, default to `stable`.

**Fetch a specific build by ID:**

```
cosa buildfetch -b <build-id> --artifact qemu --decompress
```

When `-b`/`--build` is given, `--stream` is not required -- the stream is
auto-detected from the build ID's version number (the third dotted component
maps to a stream, e.g. `.2.` = `testing`, `.3.` = `stable`). Read
`src/cmd-buildfetch` for the full version-to-stream mapping. If `--stream`
is also provided it must match or the command will error.

**If the user wants a non-qemu artifact:** replace `--artifact qemu` with the
appropriate artifact name (e.g., `metal`, `aws`, `gcp`). But note that cloud
platform workflows are better served by the **cosa-platforms** skill.

### Step 3: Launch the VM

```
cosa run
```

This launches a QEMU VM using the latest build image with `-snapshot` (changes
are discarded on exit). By default it establishes an SSH connection with
auto-login as the `core` user.

**Common options** (read `docs/cosa/run.md` for the full list):

| Flag | Purpose |
|------|---------|
| `-c` / `--devshell-console` | Use serial console instead of SSH (see full boot, GRUB menu) |
| `--qemu-image PATH` | Use a specific qcow2 image instead of the latest build |
| `-B` / `--butane PATH` | Pass a Butane config for the VM |
| `-i` / `--ignition PATH` | Pass an Ignition config for the VM |
| `--add-disk SIZE[:OPTS]` | Attach additional disks |
| `--kargs 'ARGS'` | Append kernel arguments |
| `-m SIZE` | Set VM memory in MB |

**Exiting the VM:**

- SSH mode: `exit` or `Ctrl-D`
- Console mode: `Ctrl-a x`

## Important notes

- Each `cosa` command (via the alias) creates a transient container. Use
  `cosa shell` for a persistent interactive session inside the container.
- `/dev/kvm` is required for both building disk images and running VMs. The
  host must be bare metal or have nested virtualization enabled.
- The build directory at `$PWD` is mounted at `/srv/` inside the container.
  Build artifacts persist across container invocations.
- The workdir's `builds/latest` symlink always points to the most recent build.
- To run kola tests against a build, load the **cosa-kola** skill. It covers
  test discovery, `cosa kola run`, upgrade tests, and result inspection.
- Fedora infrastructure services (like Bodhi or Koji) are behind Anubis to
  prevent abuse. When querying APIs or web pages for information set a
  User-Agent and Accept headers to increase the chance of making it
  through unchallenged.