Class: Container
An OCI-compatible container, also known as a Docker container.
Extends
BaseClient
Constructors
new Container()
new Container(
parent?,_id?,_envVariable?,_exitCode?,_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
• _exitCode?: number
• _export?: string
• _imageRef?: string
• _label?: string
• _platform?: Platform
• _publish?: string
• _stderr?: string
• _stdout?: string
• _sync?: ContainerID
• _up?: Void
• _user?: string
• _workdir?: string
Returns
Overrides
BaseClient.constructor
Methods
asService()
asService():
Service
Turn the container into a Service.
Be sure to set any exposed ports before this conversion.
Returns
asTarball()
asTarball(
opts?):File
Returns a File representing the container serialized to a tarball.
Parameters
• opts?: ContainerAsTarballOpts
Returns
build()
build(
context,opts?):Container
Initializes this container from a Dockerfile build.
Parameters
• context: Directory
Directory context used by the Dockerfile.
• opts?: ContainerBuildOpts
Returns
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
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[]>
exitCode()
exitCode():
Promise<number>
The exit code of the last executed command.
Returns an error if no command was set.
Returns
Promise<number>
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
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
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
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
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
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
stderr()
stderr():
Promise<string>
The error stream of the last executed command.
Returns an error if no command was set.
Returns
Promise<string>
stdout()
stdout():
Promise<string>
The output stream of the last executed command.
Returns an error if no command was set.
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
withoutAnnotation()
withoutAnnotation(
name):Container
Retrieves this container minus the given OCI annotation.
Parameters
• name: string
The name of the annotation.
Returns
withoutDefaultArgs()
withoutDefaultArgs():
Container
Retrieves this container with unset default arguments for future commands.
Returns
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
withoutEntrypoint()
withoutEntrypoint(
opts?):Container
Retrieves this container with an unset command entrypoint.
Parameters
• opts?: ContainerWithoutEntrypointOpts
Returns
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
withoutExposedPort()
withoutExposedPort(
port,opts?):Container
Unexpose a previously exposed port.
Parameters
• port: number
Port number to unexpose
• opts?: ContainerWithoutExposedPortOpts
Returns
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
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
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
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
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
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
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
withoutUser()
withoutUser():
Container
Retrieves this container with an unset command user.
Should default to root.
Returns
withoutWorkdir()
withoutWorkdir():
Container
Retrieves this container with an unset working directory.
Should default to "/".
Returns
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
withRootfs()
withRootfs(
directory):Container
Retrieves the container with the given directory mounted to /.
Parameters
• directory: Directory
Directory to mount.
Returns
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
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
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
withUser()
withUser(
name):Container
Retrieves this container with a different command user.
Parameters
• name: string
The user to set (e.g., "root").
Returns
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
workdir()
workdir():
Promise<string>
Retrieves the working directory for all commands.
Returns
Promise<string>