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@fe97fb60a776e3754f85b4ad6e9e27c1af821a2a

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@fe97fb60a776e3754f85b4ad6e9e27c1af821a2a 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@fe97fb60a776e3754f85b4ad6e9e27c1af821a2a 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@fe97fb60a776e3754f85b4ad6e9e27c1af821a2a 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@fe97fb60a776e3754f85b4ad6e9e27c1af821a2a 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 that holds the project’s devbox.json or devbox.jsonc and lockfile, after devbox install realises the declared packages into the cached Nix store. It adds only the manifest, so the lockfile keys the install layer rather than every source change.

Return Type 
Container !
Example
dagger -m github.com/MacroPower/x/toolchains/devbox@fe97fb60a776e3754f85b4ad6e9e27c1af821a2a 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@fe97fb60a776e3754f85b4ad6e9e27c1af821a2a 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@fe97fb60a776e3754f85b4ad6e9e27c1af821a2a call \
 with-source
func (m *MyModule) Example() *dagger.Container  {
	return dag.
			Devbox().
			Withsource()
}
@function
def example() -> dagger.Container:
	return (
		dag.devbox()
		.withsource()
	)
@func()
example(): Container {
	return dag
		.devbox()
		.withSource()
}