Skip to main content

Class: Container

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

Extends​

  • BaseClient

Constructors​

new Container()​

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

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

Parameters​

• parent?

• parent.ctx?: Context

• parent.queryTree?: QueryTree[]

• _id?: ContainerID

• _envVariable?: string

• _export?: string

• _imageRef?: string

• _label?: string

• _platform?: Platform

• _publish?: string

• _stderr?: string

• _stdout?: string

• _sync?: ContainerID

• _up?: Void

• _user?: string

• _workdir?: string

Returns​

Container

Overrides​

BaseClient.constructor

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​

• opts?: ContainerAsTarballOpts

Returns​

File

build()​

build(context, opts?): Container

Initializes this container from a Dockerfile build.

Parameters​

• 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[]>

directory()​

directory(path, opts?): Directory

Retrieves a directory at the given path.

Mounts are included.

Parameters​

• path: string

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

• opts?: ContainerDirectoryOpts

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​

• 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[]>

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 accessible to this container.

This currently works for Nvidia devices only.

Parameters​

• devices: string[]

List of devices to be accessible to this container.

Returns​

Container

export()​

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

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

It can also export platform variants.

Parameters​

• path: string

Host's destination path (e.g., "./tarball").

Path can be relative to the engine's workdir or absolute.

• opts?: ContainerExportOpts

Returns​

Promise<string>

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, opts?): File

Retrieves a file at the given path.

Mounts are included.

Parameters​

• path: string

The path of the file to retrieve (e.g., "./README.md").

• opts?: ContainerFileOpts

Returns​

File

from()​

from(address): Container

Initializes this container from a pulled base image.

Parameters​

• address: string

Image'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​

• 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: string

The 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[]>

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​

• 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>

terminal()​

terminal(opts?): Container

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

Parameters​

• opts?: ContainerTerminalOpts

Returns​

Container

up()​

up(opts?): Promise<void>

Starts a Service and creates a tunnel that forwards traffic from the caller's network to that service.

Be sure to set any exposed ports before calling this api.

Parameters​

• opts?: ContainerUpOpts

Returns​

Promise<void>

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​

• arg

Returns​

Container

withAnnotation()​

withAnnotation(name, value): Container

Retrieves this container plus the given OCI anotation.

Parameters​

• name: string

The name of the annotation.

• value: string

The value of the annotation.

Returns​

Container

withDefaultArgs()​

withDefaultArgs(args): Container

Configures default arguments for future commands.

Parameters​

• args: string[]

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

Returns​

Container

withDefaultTerminalCmd()​

withDefaultTerminalCmd(args, opts?): Container

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

Parameters​

• args: string[]

The args of the command.

• opts?: ContainerWithDefaultTerminalCmdOpts

Returns​

Container

withDirectory()​

withDirectory(path, directory, opts?): Container

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

Parameters​

• 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, opts?): Container

Retrieves this container but with a different command entrypoint.

Parameters​

• args: string[]

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​

• 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​

• 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

Parameters​

• port: number

Port 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​

• path: string

Location of the copied file (e.g., "/tmp/file.txt").

• source: File

Identifier 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​

• path: string

Location where copied files should be placed (e.g., "/src").

• sources: File[]

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​

• 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​

• 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​

• 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​

• 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​

• 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, opts?): Container

Retrieves this container plus a temporary directory mounted at the given path. Any writes will be ephemeral to a single withExec call; they will not be persisted to subsequent withExecs.

Parameters​

• path: string

Location of the temporary directory (e.g., "/tmp/temp_dir").

• opts?: ContainerWithMountedTempOpts

Returns​

Container

withNewFile()​

withNewFile(path, contents, opts?): Container

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

Parameters​

• path: string

Location of the written file (e.g., "/tmp/file.txt").

• contents: string

Content of the file to write (e.g., "Hello world!").

• opts?: ContainerWithNewFileOpts

Returns​

Container

withoutAnnotation()​

withoutAnnotation(name): Container

Retrieves this container minus the given OCI annotation.

Parameters​

• name: string

The name of the annotation.

Returns​

Container

withoutDefaultArgs()​

withoutDefaultArgs(): Container

Retrieves this container with unset default arguments for future commands.

Returns​

Container

withoutDirectory()​

withoutDirectory(path, opts?): Container

Retrieves this container with the directory at the given path removed.

Parameters​

• path: string

Location of the directory to remove (e.g., ".github/").

• opts?: ContainerWithoutDirectoryOpts

Returns​

Container

withoutEntrypoint()​

withoutEntrypoint(opts?): Container

Retrieves this container with an unset command entrypoint.

Parameters​

• opts?: ContainerWithoutEntrypointOpts

Returns​

Container

withoutEnvVariable()​

withoutEnvVariable(name): Container

Retrieves this container minus the given environment variable.

Parameters​

• name: string

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

Returns​

Container

withoutExposedPort()​

withoutExposedPort(port, opts?): Container

Unexpose a previously exposed port.

Parameters​

• port: number

Port number to unexpose

• opts?: ContainerWithoutExposedPortOpts

Returns​

Container

withoutFile()​

withoutFile(path, opts?): Container

Retrieves this container with the file at the given path removed.

Parameters​

• path: string

Location of the file to remove (e.g., "/file.txt").

• opts?: ContainerWithoutFileOpts

Returns​

Container

withoutFiles()​

withoutFiles(paths, opts?): Container

Retrieves this container with the files at the given paths removed.

Parameters​

• paths: string[]

Location of the files to remove (e.g., ["/file.txt"]).

• opts?: ContainerWithoutFilesOpts

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​

• name: string

The name of the label to remove (e.g., "org.opencontainers.artifact.created").

Returns​

Container

withoutMount()​

withoutMount(path, opts?): Container

Retrieves this container after unmounting everything at the given path.

Parameters​

• path: string

Location of the cache directory (e.g., "/cache/node_modules").

• opts?: ContainerWithoutMountOpts

Returns​

Container

withoutRegistryAuth()​

withoutRegistryAuth(address): Container

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

Parameters​

• 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

withoutSecretVariable()​

withoutSecretVariable(name): Container

Retrieves this container minus the given environment variable containing the secret.

Parameters​

• name: string

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

Returns​

Container

withoutUnixSocket()​

withoutUnixSocket(path, opts?): Container

Retrieves this container with a previously added Unix socket removed.

Parameters​

• path: string

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

• opts?: ContainerWithoutUnixSocketOpts

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

withRegistryAuth()​

withRegistryAuth(address, username, secret): Container

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

Parameters​

• 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(directory): Container

Retrieves the container with the given directory mounted to /.

Parameters​

• directory: Directory

Directory to mount.

Returns​

Container

withSecretVariable()​

withSecretVariable(name, secret): Container

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

Parameters​

• 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.

Parameters​

• alias: string

A name that can be used to reach the service from the container

• service: Service

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​

• 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: string

The user to set (e.g., "root").

Returns​

Container

withWorkdir()​

withWorkdir(path, opts?): Container

Retrieves this container with a different working directory.

Parameters​

• path: string

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

• opts?: ContainerWithWorkdirOpts

Returns​

Container

workdir()​

workdir(): Promise<string>

Retrieves the working directory for all commands.

Returns​

Promise<string>