Dagger
Search

devbox

installing and caching the packages declared in its devbox.json so CI uses
the same toolchain as local development. The full command surface stays in
the consuming project, which composes Run with its own scripts.

Installation

dagger install github.com/MacroPower/x/toolchains/devbox@8990610a338bb60f9aa8708d5fa89e1c3c6725dc

Entrypoint

Return Type 
Devbox !
Arguments
NameTypeDefault ValueDescription
sourceDirectory -Project source directory. Ignore patterns belong in the consuming project's root dagger.json customizations, not here.
imageString -Prebuilt devbox container image. When empty, the image is built in-module from the debian base with pinned Nix and devbox.
cacheNamespaceString -Namespace prefix for the Nix store cache volume. Override to avoid collisions when multiple projects share an engine.
Example
dagger -m github.com/MacroPower/x/toolchains/devbox@8990610a338bb60f9aa8708d5fa89e1c3c6725dc call \

func (m *MyModule) Example() *dagger.Devbox  {
	return dag.
			Devbox()
}
@function
def example() -> dagger.Devbox:
	return (
		dag.devbox()
	)
@func()
example(): Devbox {
	return dag
		.devbox()
}

Types

Devbox 🔗

Devbox runs commands inside a project’s Devbox environment. Create instances with [New].

source() 🔗

Project source directory.

Return Type 
Directory !
Example
dagger -m github.com/MacroPower/x/toolchains/devbox@8990610a338bb60f9aa8708d5fa89e1c3c6725dc call \
 source
func (m *MyModule) Example() *dagger.Directory  {
	return dag.
			Devbox().
			Source()
}
@function
def example() -> dagger.Directory:
	return (
		dag.devbox()
		.source()
	)
@func()
example(): Directory {
	return dag
		.devbox()
		.source()
}

image() 🔗

Image, when set, is a prebuilt devbox container image with Nix and the devbox CLI preinstalled and /nix owned by the devbox user. When empty, an equivalent image is built in-module from the debian base.

Return Type 
String !
Example
dagger -m github.com/MacroPower/x/toolchains/devbox@8990610a338bb60f9aa8708d5fa89e1c3c6725dc call \
 image
func (m *MyModule) Example(ctx context.Context) string  {
	return dag.
			Devbox().
			Image(ctx)
}
@function
async def example() -> str:
	return await (
		dag.devbox()
		.image()
	)
@func()
async example(): Promise<string> {
	return dag
		.devbox()
		.image()
}

base() 🔗

Base returns the devbox image with the Nix store mounted as a cache volume. The volume is seeded from the image’s own store so the bootstrap Nix installation keeps working, then accumulates installed packages across runs. Source is not mounted.

The cache key includes the image identity — the devbox and Nix versions for the in-module build, or the image reference for an override — because the seed (Source) and Owner only take effect when the volume is first created. Keying on the identity rotates the volume when the image is bumped, so a new image’s bootstrap store is never shadowed by a stale snapshot. Writes are serialized (Locked) since the Nix store is backed by a SQLite database that concurrent writers can corrupt.

Return Type 
Container !
Example
dagger -m github.com/MacroPower/x/toolchains/devbox@8990610a338bb60f9aa8708d5fa89e1c3c6725dc call \
 base
func (m *MyModule) Example() *dagger.Container  {
	return dag.
			Devbox().
			Base()
}
@function
def example() -> dagger.Container:
	return (
		dag.devbox()
		.base()
	)
@func()
example(): Container {
	return dag
		.devbox()
		.base()
}

install() 🔗

Install returns a container with the project’s devbox.json (and lockfile) added and devbox install run, so the declared packages are realised into the cached Nix store. Only the manifest is added, so the install layer is keyed on the lockfile rather than on every source change.

Return Type 
Container !
Example
dagger -m github.com/MacroPower/x/toolchains/devbox@8990610a338bb60f9aa8708d5fa89e1c3c6725dc call \
 install
func (m *MyModule) Example() *dagger.Container  {
	return dag.
			Devbox().
			Install()
}
@function
def example() -> dagger.Container:
	return (
		dag.devbox()
		.install()
	)
@func()
example(): Container {
	return dag
		.devbox()
		.install()
}

run() 🔗

Run executes a command inside the devbox environment (equivalent to devbox run -- <args>) and returns its standard output. Use a shell form (e.g. [“sh”, “-c”, “…”]) for pipelines or multiple commands.

Return Type 
String !
Arguments
NameTypeDefault ValueDescription
args[String ! ] !-

Command and arguments to run inside the environment.

Example
dagger -m github.com/MacroPower/x/toolchains/devbox@8990610a338bb60f9aa8708d5fa89e1c3c6725dc call \
 run --args string1 --args string2
func (m *MyModule) Example(ctx context.Context, args []string) string  {
	return dag.
			Devbox().
			Run(ctx, args)
}
@function
async def example(args: List[str]) -> str:
	return await (
		dag.devbox()
		.run(args)
	)
@func()
async example(args: string[]): Promise<string> {
	return dag
		.devbox()
		.run(args)
}

withSource() 🔗

WithSource returns the install container with the full project source overlaid on top of the installed environment. Exposed so consumers can chain further steps or wrap it (e.g. with a cache-bust) for benchmarks. Source is overlaid rather than replacing the mount, so the .devbox state produced by Install survives (provided the consumer ignores .devbox).

Return Type 
Container !
Example
dagger -m github.com/MacroPower/x/toolchains/devbox@8990610a338bb60f9aa8708d5fa89e1c3c6725dc call \
 with-source
func (m *MyModule) Example() *dagger.Container  {
	return dag.
			Devbox().
			WithSource()
}
@function
def example() -> dagger.Container:
	return (
		dag.devbox()
		.with_source()
	)
@func()
example(): Container {
	return dag
		.devbox()
		.withSource()
}