Skip to main content

Dagger NodeJS SDK

api/client.gen.Container

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

Hierarchy

  • BaseClient

    Container

Constructors

constructor

new Container(parent?, _id?, _envVariable?, _export?, _imageRef?, _label?, _platform?, _publish?, _stderr?, _stdout?, _sync?, _user?, _workdir?): Container

Constructor is used for internal usage only, do not create object from it.

Parameters

NameType
parent?Object
parent.ctxContext
parent.queryTree?QueryTree[]
_id?ContainerID
_envVariable?string
_export?boolean
_imageRef?string
_label?string
_platform?Platform
_publish?string
_stderr?string
_stdout?string
_sync?ContainerID
_user?string
_workdir?string

Returns

Container

Overrides

BaseClient.constructor

Properties

_envVariable

Private Optional Readonly _envVariable: string = undefined


_export

Private Optional Readonly _export: boolean = undefined


_id

Private Optional Readonly _id: ContainerID = undefined


_imageRef

Private Optional Readonly _imageRef: string = undefined


_label

Private Optional Readonly _label: string = undefined


_platform

Private Optional Readonly _platform: Platform = undefined


_publish

Private Optional Readonly _publish: string = undefined


_stderr

Private Optional Readonly _stderr: string = undefined


_stdout

Private Optional Readonly _stdout: string = undefined


_sync

Private Optional Readonly _sync: ContainerID = undefined


_user

Private Optional Readonly _user: string = undefined


_workdir

Private Optional Readonly _workdir: string = undefined

Methods

asService

asService(): Service

Turn the container into a Service.

Be sure to set any exposed ports before this conversion.

Returns

Service


asTarball

asTarball(opts?): File

Returns a File representing the container serialized to a tarball.

Parameters

NameType
opts?ContainerAsTarballOpts

Returns

File


build

build(context, opts?): Container

Initializes this container from a Dockerfile build.

Parameters

NameTypeDescription
contextDirectoryDirectory context used by the Dockerfile.
opts?ContainerBuildOpts-

Returns

Container


defaultArgs

defaultArgs(): Promise<string[]>

Retrieves default arguments for future commands.

Returns

Promise<string[]>


directory

directory(path): Directory

Retrieves a directory at the given path.

Mounts are included.

Parameters

NameTypeDescription
pathstringThe path of the directory to retrieve (e.g., "./src").

Returns

Directory


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

NameTypeDescription
namestringThe 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[]>


experimentalWithAllGPUs

experimentalWithAllGPUs(): Container

EXPERIMENTAL API! Subject to change/removal at any time.

Configures all available GPUs on the host to be accessible to this container.

This currently works for Nvidia devices only.

Returns

Container


experimentalWithGPU

experimentalWithGPU(devices): Container

EXPERIMENTAL API! Subject to change/removal at any time.

Configures the provided list of devices to be accesible to this container.

This currently works for Nvidia devices only.

Parameters

NameTypeDescription
devicesstring[]List of devices to be accessible to this container.

Returns

Container


export

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

Writes the container as an OCI tarball to the destination file path on the host.

Return true on success.

It can also export platform variants.

Parameters

NameTypeDescription
pathstringHost'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.

This includes ports already exposed by the image, even if not explicitly added with dagger.

Returns

Promise<Port[]>


file

file(path): File

Retrieves a file at the given path.

Mounts are included.

Parameters

NameTypeDescription
pathstringThe 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

NameTypeDescription
addressstringImage's address from its registry. Formatted as [host]/[user]/[repo]:[tag] (e.g., "docker.io/dagger/dagger:main").

Returns

Container


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.

Parameters

NameTypeDescription
sourceFileFile to read the container from.
opts?ContainerImportOpts-

Returns

Container


label

label(name): Promise<string>

Retrieves the value of the specified label.

Parameters

NameTypeDescription
namestringThe name of the label (e.g., "org.opencontainers.artifact.created").

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

NameTypeDescription
namestringName of the sub-pipeline.
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

NameTypeDescription
addressstringRegistry'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>


terminal

terminal(opts?): Terminal

Return an interactive terminal for this container using its configured default terminal command if not overridden by args (or sh as a fallback default).

Parameters

NameType
opts?ContainerTerminalOpts

Returns

Terminal


user

user(): Promise<string>

Retrieves the user to be set for all commands.

Returns

Promise<string>


with

with(arg): Container

Call the provided function with current Container.

This is useful for reusability and readability by not breaking the calling chain.

Parameters

NameType
arg(param: Container) => Container

Returns

Container


withDefaultArgs

withDefaultArgs(args): Container

Configures default arguments for future commands.

Parameters

NameTypeDescription
argsstring[]Arguments to prepend to future executions (e.g., ["-v", "--no-cache"]).

Returns

Container


withDefaultTerminalCmd

withDefaultTerminalCmd(args): Container

Set the default command to invoke for the container's terminal API.

Parameters

NameTypeDescription
argsstring[]The args of the command.

Returns

Container


withDirectory

withDirectory(path, directory, opts?): Container

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

Parameters

NameTypeDescription
pathstringLocation of the written directory (e.g., "/tmp/directory").
directoryDirectoryIdentifier of the directory to write
opts?ContainerWithDirectoryOpts-

Returns

Container


withEntrypoint

withEntrypoint(args, opts?): Container

Retrieves this container but with a different command entrypoint.

Parameters

NameTypeDescription
argsstring[]Entrypoint to use for future executions (e.g., ["go", "run"]).
opts?ContainerWithEntrypointOpts-

Returns

Container


withEnvVariable

withEnvVariable(name, value, opts?): Container

Retrieves this container plus the given environment variable.

Parameters

NameTypeDescription
namestringThe name of the environment variable (e.g., "HOST").
valuestringThe 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

NameTypeDescription
argsstring[]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

Parameters

NameTypeDescription
portnumberPort number to expose
opts?ContainerWithExposedPortOpts-

Returns

Container


withFile

withFile(path, source, opts?): Container

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

Parameters

NameTypeDescription
pathstringLocation of the copied file (e.g., "/tmp/file.txt").
sourceFileIdentifier of the file to copy.
opts?ContainerWithFileOpts-

Returns

Container


withFiles

withFiles(path, sources, opts?): Container

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

Parameters

NameTypeDescription
pathstringLocation where copied files should be placed (e.g., "/src").
sourcesFile[]Identifiers of the files to copy.
opts?ContainerWithFilesOpts-

Returns

Container


withFocus

withFocus(): Container

Indicate that subsequent operations should be featured more prominently in the UI.

Returns

Container


withLabel

withLabel(name, value): Container

Retrieves this container plus the given label.

Parameters

NameTypeDescription
namestringThe name of the label (e.g., "org.opencontainers.artifact.created").
valuestringThe 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

NameTypeDescription
pathstringLocation of the cache directory (e.g., "/cache/node_modules").
cacheCacheVolumeIdentifier 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

NameTypeDescription
pathstringLocation of the mounted directory (e.g., "/mnt/directory").
sourceDirectoryIdentifier 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

NameTypeDescription
pathstringLocation of the mounted file (e.g., "/tmp/file.txt").
sourceFileIdentifier 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

NameTypeDescription
pathstringLocation of the secret file (e.g., "/tmp/secret.txt").
sourceSecretIdentifier 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

NameTypeDescription
pathstringLocation 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

NameTypeDescription
pathstringLocation 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

NameTypeDescription
addressstringRegistry's address to bind the authentication to. Formatted as [host]/[user]/[repo]:[tag] (e.g. docker.io/dagger/dagger:main).
usernamestringThe username of the registry's account (e.g., "Dagger").
secretSecretThe API key, password or token to authenticate to this registry.

Returns

Container


withRootfs

withRootfs(directory): Container

Retrieves the container with the given directory mounted to /.

Parameters

NameTypeDescription
directoryDirectoryDirectory to mount.

Returns

Container


withSecretVariable

withSecretVariable(name, secret): Container

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

Parameters

NameTypeDescription
namestringThe name of the secret variable (e.g., "API_SECRET").
secretSecretThe 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.

Parameters

NameTypeDescription
aliasstringA name that can be used to reach the service from the container
serviceServiceIdentifier 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

NameTypeDescription
pathstringLocation of the forwarded Unix socket (e.g., "/tmp/socket").
sourceSocketIdentifier of the socket to forward.
opts?ContainerWithUnixSocketOpts-

Returns

Container


withUser

withUser(name): Container

Retrieves this container with a different command user.

Parameters

NameTypeDescription
namestringThe user to set (e.g., "root").

Returns

Container


withWorkdir

withWorkdir(path): Container

Retrieves this container with a different working directory.

Parameters

NameTypeDescription
pathstringThe path to set as the working directory (e.g., "/app").

Returns

Container


withoutDefaultArgs

withoutDefaultArgs(): Container

Retrieves this container with unset default arguments for future commands.

Returns

Container


withoutEntrypoint

withoutEntrypoint(opts?): Container

Retrieves this container with an unset command entrypoint.

Parameters

NameType
opts?ContainerWithoutEntrypointOpts

Returns

Container


withoutEnvVariable

withoutEnvVariable(name): Container

Retrieves this container minus the given environment variable.

Parameters

NameTypeDescription
namestringThe name of the environment variable (e.g., "HOST").

Returns

Container


withoutExposedPort

withoutExposedPort(port, opts?): Container

Unexpose a previously exposed port.

Parameters

NameTypeDescription
portnumberPort number to unexpose
opts?ContainerWithoutExposedPortOpts-

Returns

Container


withoutFocus

withoutFocus(): Container

Indicate that subsequent operations should not be featured more prominently in the UI.

This is the initial state of all containers.

Returns

Container


withoutLabel

withoutLabel(name): Container

Retrieves this container minus the given environment label.

Parameters

NameTypeDescription
namestringThe 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

NameTypeDescription
pathstringLocation 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

NameTypeDescription
addressstringRegistry'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

NameTypeDescription
pathstringLocation of the socket to remove (e.g., "/tmp/socket").

Returns

Container


withoutUser

withoutUser(): Container

Retrieves this container with an unset command user.

Should default to root.

Returns

Container


withoutWorkdir

withoutWorkdir(): Container

Retrieves this container with an unset working directory.

Should default to "/".

Returns

Container


workdir

workdir(): Promise<string>

Retrieves the working directory for all commands.

Returns

Promise<string>