Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,26 @@
# Unreleased

## Breaking changes
- Config: Replaced `resources.rootfsSize` with a new `rootfs.size` setting (see
below) and added stricter up-front validation. The old field (theoretically)
accepted any non-empty string; the new one enforces a QEMU-compatible size
syntax – a positive integer with a *mandatory* K/M/G/T suffix.
- Config: `resources.memory` now requires a mandatory unit suffix (K/M/G/T), for
consistency with `rootfs.size` (see above).


## Features
- Config: Add new `rootfs.image` setting to expose a [Gondolin
feature](https://earendil-works.github.io/gondolin/custom-images/) that allows
configuring a custom OCI container image to be used for the VM's rootfs
instead of Gondolin's default `alpine-base` image. (The kernel is still taken
from Alpine, though.) The OCI image can either be an existing one or it can be
built from a Dockerfile/Containerfile.
- Config: The new `rootfs.size` setting can be used both with the default VM
rootfs (same behavior as the old `resources.rootfsSize`), in which case it
grows the file system after boot (using `resize2fs`), or with a custom image
(`rootfs.image`), in which case the size gets baked in at build time.


# 0.6.0 (2026-10-09)

Expand Down
90 changes: 74 additions & 16 deletions docs/Configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,19 +10,56 @@ that VSCode uses, too. An informal specification (not by Microsoft) can be found
at https://jsonc.org/.


## Config inheritance
## Config options
A detailed documentation of all config options is still work in progress. In the
meantime, please refer to [`/src/config/schema.ts`](../src/config/schema.ts).


## Config inheritance & merging
Configs in child directories inherit from configs in parent directories (and so
on), which in turn inherit from the global `~/.config/tuor/config.json`. In
general, child settings override parent settings, except in the following cases:
on), which in turn inherit from the global `~/.config/tuor/config.json`. The
individual config files don't need to provide all settings that are required by
the schema (see above); only the end result after merging them gets validated.

- Env vars, mounts, volumes get merged (shallow merge).
- Boot commands are concatenated (parent commands run first).
- Network: Child network mode overrides parent mode; allowed hosts are merged.
Relative host path references in a given config file (e.g. `workdir: "../foo"`)
are always evaluated relative to *that* config file's location, before it
potentially gets merged with other configs.


## Config options
A detailed documentation of all config options is still work in progress. In the
meantime, please refer to [`/src/config/schema.ts`](../src/config/schema.ts).
**How inheritance works:** In general, top-level settings in the child config
override top-level settings in the parent config. However, in some cases
settings are deep-merged and the config inheritance algorithm descends down the
config schema tree, or values are concatenated with the parent config (e.g. in
case of lists), as indicated below:

```jsonc
{
"bootCommands": [], // concatenate with parent list (parent commands run first)
"env": {}, // concatenate/shallow-merge with parent dictionary
"guestUser?": {}, // override parent
"mounts": [], // concatenate with parent list
"network": {
"mode": "", // override parent
"allowedHosts": [], // concatenate with parent list
"allowedInternalHosts": [], // concatenate with parent list
},
"qemu": {
"accel": "", // override parent
"cpu": "", // override parent
"machineType": "", // override parent
}, // ?
"resources": {
"cpus": "", // override parent
"memory": "", // override parent
}, // ?
"rootfs": {
"image": {}, // override parent
"size": "", // override parent
},
"volumes": [], // concatenate with parent list
"workdir": {} /* or string value */, // override parent
}
```


## Variables
Expand All @@ -36,7 +73,7 @@ is validated):
// $PWD lets you mount wherever you launched Tuor from:
{ "hostPath": "$PWD", "guestPath": "/workspace", "mode": "readwrite" }
],
"resources": { "rootfsSize": "${ROOTFS_SIZE}" },
"rootfs": { "size": "${ROOTFS_SIZE}" },
// Use $$ for a literal dollar sign:
"env": { "PROMPT": "$$ " }
}
Expand Down Expand Up @@ -109,12 +146,33 @@ that is not set on the host is an error.
// `qemu.cpu` (the emulated CPU model).
"resources": {
"cpus": 4, // vCPU count (positive integer)
"memory": "2G", // RAM, QEMU syntax (e.g. "512M", "2G")
// Minimum virtual disk size (COW overlay, so actual host usage stays
// sparse). Note that the virtual disk will be discarded on VM shutdown,
// so it is not meant for persisting data across VM boots. (Use mounts &
// volumes, instead!)
"rootfsSize": "2G"
"memory": "2G" // RAM, QEMU syntax (e.g. "512M", "2G")
},
"rootfs": {
"image": {
// Whole OCI image ref (`:tag` or `@sha256:…`). Omit the whole `image`
// block to boot Gondolin's default alpine-base image.
"ref": "docker.io/library/debian:bookworm-slim",
// Optional: container engine used to pull & export the image. Omit to let
// Gondolin auto-detect (docker, else podman).
"engine": "docker",
// Optional (default "if-not-present"): where the image comes from on the
// runs that build. "always" to re-pull every time, "never" to use the
// engine's local image store only (and fail if the image isn't in it).
"pullPolicy": "if-not-present",
// Optional (default "if-not-present"): whether to reuse the guest assets
// Tuor cached for this `ref`. "always" rebuilds them every run. Note that
// `ref`, not the image contents, is the cache identity, so a moving tag
// needs *this* set to "always" — `pullPolicy` alone won't refresh
// anything, because a cache hit skips the build that would pull.
"buildPolicy": "if-not-present"
},
// Optional: total rootfs size — a positive integer plus a *mandatory*
// K/M/G/T suffix. Grow-only (never shrinks).
// Note that the virtual disk is discarded on VM shutdown, so it is not
// meant for persisting data across VM boots. (Use mounts & volumes,
// instead!)
"size": "8G"
},
// Guest user (numeric uid/gid) the shell runs under and that mounted
// directories are presented as owned by. `homedir` (optional, default /root)
Expand Down
14 changes: 14 additions & 0 deletions docs/Limitations & known issues.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,20 @@ reason, the user (and his home dir) are currently hard-coded at the Tuor config
level, though you could of course `su` to a non-root user inside the VM.


## VM might hang during boot when using custom images and memory is set to exactly 2 GiB
This is an [upstream issue in
QEMU](https://gitlab.com/qemu-project/qemu/-/work_items/3454). Whether or not
you will actually run into this bug depends on the size of the VM's initramfs
(mod 4096) that Gondolin produces, which [is a bit of a
gamble](https://github.com/earendil-works/gondolin/issues/166). If you do, as a
workaround set your VM's memory to a value slightly different from 2 GiB.


## The initramfs of custom images is unusually big (~ 50 MiB) and much bigger than the default image's one
See the note at the end of the aforementioned
https://github.com/earendil-works/gondolin/issues/166 .


## Mounts & volumes don't support creating Unix file sockets
This is a limitation in Gondolin's `sandboxfs` FUSE, which does not support the
`MKNOD` syscall.
Expand Down
16 changes: 14 additions & 2 deletions src/config/defaults.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -75,16 +75,28 @@ describe("applyConfigDefaults", () => {
});
});

describe("rootfs", () => {
test("leaves an absent rootfs absent (no empty object synthesized)", () => {
expect(applyConfigDefaults(config()).rootfs).toBeUndefined();
});

test("invents no image for a rootfs that only sets size", () => {
const result = applyConfigDefaults(config({ rootfs: { size: "8G" } }));
expect(result.rootfs).toEqual({ size: "8G" });
expect(result.rootfs && "image" in result.rootfs).toBe(false);
});
});

test("leaves other fields untouched", () => {
const input = config({
guestUser: { uid: 0, gid: 0 },
workdir: "/work",
resources: { rootfsSize: "2G" },
resources: { memory: "2G" },
});
const result = applyConfigDefaults(input);
expect(result.guestUser).toEqual({ uid: 0, gid: 0, homedir: "/root" });
expect(result.workdir).toBe("/work");
expect(result.resources).toEqual({ rootfsSize: "2G" });
expect(result.resources).toEqual({ memory: "2G" });
});

test("does not mutate the input config", () => {
Expand Down
18 changes: 10 additions & 8 deletions src/config/defaults.ts
Original file line number Diff line number Diff line change
Expand Up @@ -41,17 +41,19 @@ export type DefaultedConfig = Omit<

/**
* Fill the config-level defaults that don't come from the arktype schema:
* `guestUser`, `workdir`, and `network` (block-all when omitted).
* `guestUser`, `workdir` and `network` (block-all when omitted).
*
* `guestUser`/`workdir` are defaulted *here* rather than in the schema so that a
* child config layer that omits them doesn't clobber a value inherited from a
* parent layer during merge (their "omitted" would otherwise be indistinguish-
* able from an explicit default). This must run after `mergeConfigs`.
* These are defaulted *here* rather than in the schema so that a child config
* layer that omits them doesn't clobber a value inherited from a parent layer
* during merge (their "omitted" would otherwise be indistinguishable from an
* explicit default, because `parseConfig` runs per layer, before the merge).
* This must run after `mergeConfigs`.
*
* Pure and dependency-free. The remaining schema defaults (mount `mode`,
* `nixLd`) are already applied by `parseConfig`; computed conversions (path
* expansion, env/secret split, nix→mounts, overlay state dirs, …) are *not*
* defaults and stay in {@link createSessionSpecFromConfig}.
* `nixLd`, `rootfs.image.pullPolicy`) are already applied by `parseConfig`;
* computed conversions (path expansion, env/secret split, nix→mounts, overlay
* state dirs, …) are *not* defaults and stay in
* {@link createSessionSpecFromConfig}.
*/
export function applyConfigDefaults(config: TuorConfig): DefaultedConfig {
const guestUser = config.guestUser ?? DEFAULT_GUEST_USER;
Expand Down
Loading
Loading