Dagger NodeJS SDK

api/client.gen.Container

An OCI-compatible container, also known as a docker container.

Hierarchy

BaseClient
↳ Container

Properties

clientHost

clientHost: string

Default Value

127.0.0.1:8080

Inherited from

BaseClient.clientHost

sessionToken

sessionToken: string

Inherited from

BaseClient.sessionToken

Methods

build

build(context, opts?): Container

Initializes this container from a Dockerfile build.

Parameters

Name	Type	Description
`context`	`Directory`	Directory context used by the Dockerfile.
`opts?`	`ContainerBuildOpts`	-

Returns

Container

defaultArgs

defaultArgs(): Promise<string[]>

Retrieves default arguments for future commands.

Returns

Promise<string[]>

Name	Type	Description
`path`	`string`	The path of the directory to retrieve (e.g., "./src").

endpoint

endpoint(opts?): Promise<string>

Retrieves an endpoint that clients can use to reach this container.

If no port is specified, the first exposed port is used. If none exist an error is returned.

If a scheme is specified, a URL is returned. Otherwise, a host:port pair is returned.

Currently experimental; set _EXPERIMENTAL_DAGGER_SERVICES_DNS=0 to disable.

Parameters

Name	Type
`opts?`	`ContainerEndpointOpts`

Returns

Promise<string>

entrypoint

entrypoint(): Promise<string[]>

Retrieves entrypoint to be prepended to the arguments of all commands.

Returns

Promise<string[]>

envVariable

envVariable(name): Promise<string>

Retrieves the value of the specified environment variable.

Parameters

Name	Type	Description
`name`	`string`	The name of the environment variable to retrieve (e.g., "PATH").

Returns

Promise<string>

envVariables

envVariables(): Promise<EnvVariable[]>

Retrieves the list of environment variables passed to commands.

Returns

Promise<EnvVariable[]>

exec

exec(opts?): Container

Retrieves this container after executing the specified command inside it.

Deprecated

Replaced by withExec.

Parameters

Name	Type
`opts?`	`ContainerExecOpts`

Returns

Container

exitCode

exitCode(): Promise<number>

Exit code of the last executed command. Zero means success.

Will execute default command if none is set, or error if there's no default.

Returns

Promise<number>

export

export(path, opts?): Promise<boolean>

Writes the container as an OCI tarball to the destination file path on the host for the specified platform variants.

Return true on success. It can also publishes platform variants.

Parameters

Name	Type	Description
`path`	`string`	Host's destination path (e.g., "./tarball"). Path can be relative to the engine's workdir or absolute.
`opts?`	`ContainerExportOpts`	-

Returns

Promise<boolean>

exposedPorts

exposedPorts(): Promise<Port[]>

Retrieves the list of exposed ports.

Currently experimental; set _EXPERIMENTAL_DAGGER_SERVICES_DNS=0 to disable.

Returns

Promise<Port[]>

file

file(path): File

Retrieves a file at the given path.

Mounts are included.

Parameters

Name	Type	Description
`path`	`string`	The path of the file to retrieve (e.g., "./README.md").

Returns

File

from

from(address): Container

Initializes this container from a pulled base image.

Parameters

Name	Type	Description
`address`	`string`	Image's address from its registry. Formatted as [host]/[user]/[repo]:[tag] (e.g., "docker.io/dagger/dagger:main").

Returns

Container

fs

fs(): Directory

Retrieves this container's root filesystem. Mounts are not included.

Deprecated

Replaced by rootfs.

Returns

Directory

hostname

hostname(): Promise<string>

Retrieves a hostname which can be used by clients to reach this container.

Currently experimental; set _EXPERIMENTAL_DAGGER_SERVICES_DNS=0 to disable.

Returns

Promise<string>

id

id(): Promise<ContainerID>

A unique identifier for this container.

Returns

Promise<ContainerID>

imageRef

imageRef(): Promise<string>

The unique image reference which can only be retrieved immediately after the 'Container.From' call.

Returns

Promise<string>

import

import(source, opts?): Container

Reads the container from an OCI tarball.

NOTE: this involves unpacking the tarball to an OCI store on the host at $XDG_CACHE_DIR/dagger/oci. This directory can be removed whenever you like.

Parameters

Name	Type	Description
`source`	`File`	File to read the container from.
`opts?`	`ContainerImportOpts`	-

Returns

Container

label

label(name): Promise<string>

Retrieves the value of the specified label.

Parameters

Name	Type
`name`	`string`

Returns

Promise<string>

labels

labels(): Promise<Label[]>

Retrieves the list of labels passed to container.

Returns

Promise<Label[]>

mounts

mounts(): Promise<string[]>

Retrieves the list of paths where a directory is mounted.

Returns

Promise<string[]>

pipeline

pipeline(name, opts?): Container

Creates a named sub-pipeline

Parameters

Name	Type	Description
`name`	`string`	Pipeline name.
`opts?`	`ContainerPipelineOpts`	-

Returns

Container

platform

platform(): Promise<Platform>

The platform this container executes and publishes as.

Returns

Promise<Platform>

publish

publish(address, opts?): Promise<string>

Publishes this container as a new image to the specified address.

Publish returns a fully qualified ref. It can also publish platform variants.

Parameters

Name	Type	Description
`address`	`string`	Registry's address to publish the image to. Formatted as [host]/[user]/[repo]:[tag] (e.g. "docker.io/dagger/dagger:main").
`opts?`	`ContainerPublishOpts`	-

Returns

Promise<string>

rootfs

rootfs(): Directory

Retrieves this container's root filesystem. Mounts are not included.

Returns

Directory

stderr

stderr(): Promise<string>

The error stream of the last executed command.

Will execute default command if none is set, or error if there's no default.

Returns

Promise<string>

stdout

stdout(): Promise<string>

The output stream of the last executed command.

Will execute default command if none is set, or error if there's no default.

Returns

Promise<string>

sync

sync(): Promise<Container>

Forces evaluation of the pipeline in the engine.

It doesn't run the default command if no exec has been set.

Returns

Promise<Container>

user

user(): Promise<string>

Retrieves the user to be set for all commands.

Returns

Promise<string>

with

with(arg): Container

Chain objects together

Example

    function AddAFewMounts(c) {
            return c
            .withMountedDirectory("/foo", new Client().host().directory("/Users/slumbering/forks/dagger"))
            .withMountedDirectory("/bar", new Client().host().directory("/Users/slumbering/forks/dagger/sdk/nodejs"))
    }

connect(async (client) => {
        const tree = await client
            .container()
            .from("alpine")
            .withWorkdir("/foo")
            .with(AddAFewMounts)
            .withExec(["ls", "-lh"])
            .stdout()
})

Parameters

Name	Type
`arg`	(`param`: `Container`) => `Container`

Returns

Container

withDefaultArgs

withDefaultArgs(opts?): Container

Configures default arguments for future commands.

Parameters

Name	Type
`opts?`	`ContainerWithDefaultArgsOpts`

Returns

Container

withDirectory

withDirectory(path, directory, opts?): Container

Retrieves this container plus a directory written at the given path.

Parameters

Name	Type	Description
`path`	`string`	Location of the written directory (e.g., "/tmp/directory").
`directory`	`Directory`	Identifier of the directory to write
`opts?`	`ContainerWithDirectoryOpts`	-

Returns

Container

withEntrypoint

withEntrypoint(args): Container

Retrieves this container but with a different command entrypoint.

Parameters

Name	Type	Description
`args`	`string`[]	Entrypoint to use for future executions (e.g., ["go", "run"]).

Returns

Container

withEnvVariable

withEnvVariable(name, value, opts?): Container

Retrieves this container plus the given environment variable.

Parameters

Name	Type	Description
`name`	`string`	The name of the environment variable (e.g., "HOST").
`value`	`string`	The value of the environment variable. (e.g., "localhost").
`opts?`	`ContainerWithEnvVariableOpts`	-

Returns

Container

withExec

withExec(args, opts?): Container

Retrieves this container after executing the specified command inside it.

Parameters

Name	Type	Description
`args`	`string`[]	Command to run instead of the container's default command (e.g., ["run", "main.go"]). If empty, the container's default command is used.
`opts?`	`ContainerWithExecOpts`	-

Returns

Container

withExposedPort

withExposedPort(port, opts?): Container

Expose a network port.

Exposed ports serve two purposes:

For health checks and introspection, when running services
For setting the EXPOSE OCI field when publishing the container

Currently experimental; set _EXPERIMENTAL_DAGGER_SERVICES_DNS=0 to disable.

Parameters

Name	Type	Description
`port`	`number`	Port number to expose
`opts?`	`ContainerWithExposedPortOpts`	-

Returns

Container

withFS

withFS(id): Container

Initializes this container from this DirectoryID.

Deprecated

Replaced by withRootfs.

Parameters

Name	Type
`id`	`Directory`

Returns

Container

withFile

withFile(path, source, opts?): Container

Retrieves this container plus the contents of the given file copied to the given path.

Parameters

Name	Type	Description
`path`	`string`	Location of the copied file (e.g., "/tmp/file.txt").
`source`	`File`	Identifier of the file to copy.
`opts?`	`ContainerWithFileOpts`	-

Returns

Container

withLabel

withLabel(name, value): Container

Retrieves this container plus the given label.

Parameters

Name	Type	Description
`name`	`string`	The name of the label (e.g., "org.opencontainers.artifact.created").
`value`	`string`	The value of the label (e.g., "2023-01-01T00:00:00Z").

Returns

Container

withMountedCache

withMountedCache(path, cache, opts?): Container

Retrieves this container plus a cache volume mounted at the given path.

Parameters

Name	Type	Description
`path`	`string`	Location of the cache directory (e.g., "/cache/node_modules").
`cache`	`CacheVolume`	Identifier of the cache volume to mount.
`opts?`	`ContainerWithMountedCacheOpts`	-

Returns

Container

withMountedDirectory

withMountedDirectory(path, source, opts?): Container

Retrieves this container plus a directory mounted at the given path.

Parameters

Name	Type	Description
`path`	`string`	Location of the mounted directory (e.g., "/mnt/directory").
`source`	`Directory`	Identifier of the mounted directory.
`opts?`	`ContainerWithMountedDirectoryOpts`	-

Returns

Container

withMountedFile

withMountedFile(path, source, opts?): Container

Retrieves this container plus a file mounted at the given path.

Parameters

Name	Type	Description
`path`	`string`	Location of the mounted file (e.g., "/tmp/file.txt").
`source`	`File`	Identifier of the mounted file.
`opts?`	`ContainerWithMountedFileOpts`	-

Returns

Container

withMountedSecret

withMountedSecret(path, source, opts?): Container

Retrieves this container plus a secret mounted into a file at the given path.

Parameters

Name	Type	Description
`path`	`string`	Location of the secret file (e.g., "/tmp/secret.txt").
`source`	`Secret`	Identifier of the secret to mount.
`opts?`	`ContainerWithMountedSecretOpts`	-

Returns

Container

withMountedTemp

withMountedTemp(path): Container

Retrieves this container plus a temporary directory mounted at the given path.

Parameters

Name	Type	Description
`path`	`string`	Location of the temporary directory (e.g., "/tmp/temp_dir").

Returns

Container

withNewFile

withNewFile(path, opts?): Container

Retrieves this container plus a new file written at the given path.

Parameters

Name	Type	Description
`path`	`string`	Location of the written file (e.g., "/tmp/file.txt").
`opts?`	`ContainerWithNewFileOpts`	-

Returns

Container

withRegistryAuth

withRegistryAuth(address, username, secret): Container

Retrieves this container with a registry authentication for a given address.

Parameters

Name	Type	Description
`address`	`string`	Registry's address to bind the authentication to. Formatted as [host]/[user]/[repo]:[tag] (e.g. docker.io/dagger/dagger:main).
`username`	`string`	The username of the registry's account (e.g., "Dagger").
`secret`	`Secret`	The API key, password or token to authenticate to this registry.

Returns

Container

withRootfs

withRootfs(id): Container

Initializes this container from this DirectoryID.

Parameters

Name	Type
`id`	`Directory`

Returns

Container

withSecretVariable

withSecretVariable(name, secret): Container

Retrieves this container plus an env variable containing the given secret.

Parameters

Name	Type	Description
`name`	`string`	The name of the secret variable (e.g., "API_SECRET").
`secret`	`Secret`	The identifier of the secret value.

Returns

Container

withServiceBinding

withServiceBinding(alias, service): Container

Establish a runtime dependency on a service.

The service will be started automatically when needed and detached when it is no longer needed, executing the default command if none is set.

The service will be reachable from the container via the provided hostname alias.

The service dependency will also convey to any files or directories produced by the container.

Currently experimental; set _EXPERIMENTAL_DAGGER_SERVICES_DNS=0 to disable.

Parameters

Name	Type	Description
`alias`	`string`	A name that can be used to reach the service from the container
`service`	`Container`	Identifier of the service container

Returns

Container

withUnixSocket

withUnixSocket(path, source, opts?): Container

Retrieves this container plus a socket forwarded to the given Unix socket path.

Parameters

Name	Type	Description
`path`	`string`	Location of the forwarded Unix socket (e.g., "/tmp/socket").
`source`	`Socket`	Identifier of the socket to forward.
`opts?`	`ContainerWithUnixSocketOpts`	-

Returns

Container

withUser

withUser(name): Container

Retrieves this container with a different command user.

Parameters

Name	Type	Description
`name`	`string`	The user to set (e.g., "root").

Returns

Container

withWorkdir

withWorkdir(path): Container

Retrieves this container with a different working directory.

Parameters

Name	Type	Description
`path`	`string`	The path to set as the working directory (e.g., "/app").

Returns

Container

withoutEnvVariable

withoutEnvVariable(name): Container

Retrieves this container minus the given environment variable.

Parameters

Name	Type	Description
`name`	`string`	The name of the environment variable (e.g., "HOST").

Returns

Container

withoutExposedPort

withoutExposedPort(port, opts?): Container

Unexpose a previously exposed port.

Currently experimental; set _EXPERIMENTAL_DAGGER_SERVICES_DNS=0 to disable.

Parameters

Name	Type	Description
`port`	`number`	Port number to unexpose
`opts?`	`ContainerWithoutExposedPortOpts`	-

Returns

Container

withoutLabel

withoutLabel(name): Container

Retrieves this container minus the given environment label.

Parameters

Name	Type	Description
`name`	`string`	The name of the label to remove (e.g., "org.opencontainers.artifact.created").

Returns

Container

withoutMount

withoutMount(path): Container

Retrieves this container after unmounting everything at the given path.

Parameters

Name	Type	Description
`path`	`string`	Location of the cache directory (e.g., "/cache/node_modules").

Returns

Container

withoutRegistryAuth

withoutRegistryAuth(address): Container

Retrieves this container without the registry authentication of a given address.

Parameters

Name	Type	Description
`address`	`string`	Registry's address to remove the authentication from. Formatted as [host]/[user]/[repo]:[tag] (e.g. docker.io/dagger/dagger:main).

Returns

Container

withoutUnixSocket

withoutUnixSocket(path): Container

Retrieves this container with a previously added Unix socket removed.

Parameters

Name	Type	Description
`path`	`string`	Location of the socket to remove (e.g., "/tmp/socket").

Returns

Container

workdir

workdir(): Promise<string>

Retrieves the working directory for all commands.

Returns

Promise<string>

Hierarchy​

Properties​

clientHost​

Inherited from​

sessionToken​

Inherited from​

Methods​

build​

Parameters​

Returns​

defaultArgs​

Returns​

directory​

Parameters​

Returns​

endpoint​

Parameters​

Returns​

entrypoint​

Returns​

envVariable​

Parameters​

Returns​

envVariables​

Returns​

exec​

Parameters​

Returns​

exitCode​

Returns​

export​

Parameters​

Returns​

exposedPorts​

Returns​

file​

Parameters​

Returns​

from​

Parameters​

Returns​

fs​

Returns​

hostname​

Returns​

id​

Returns​

imageRef​

Returns​

import​

Parameters​

Returns​

label​

Parameters​

Returns​

labels​

Returns​

mounts​

Returns​

pipeline​

Parameters​

Returns​

platform​

Returns​

publish​

Parameters​

Returns​

rootfs​

Returns​

stderr​

Returns​

stdout​

Returns​

sync​

Returns​

user​

Returns​

with​

Parameters​

Returns​

Hierarchy

Properties

clientHost

Inherited from

sessionToken

Inherited from

Methods

build

Parameters

Returns

defaultArgs

Returns

directory

Parameters

Returns

endpoint

Parameters

Returns

entrypoint

Returns

envVariable

Parameters

Returns

envVariables

Returns

exec

Parameters

Returns

exitCode

Returns

export

Parameters

Returns

exposedPorts

Returns

file

Parameters

Returns

from

Parameters

Returns

fs

Returns

hostname

Returns

id

Returns

imageRef

Returns

import

Parameters

Returns

label

Parameters

Returns

labels

Returns

mounts

Returns

pipeline

Parameters

Returns

platform

Returns

publish

Parameters

Returns

rootfs

Returns

stderr

Returns

stdout

Returns

sync

Returns

user

Returns

with

Parameters

Returns