Execute commands

You can execute commands within your service or job containers using the CLI, JavaScript client, or via the Northflank application.

Executing a command will normally spawn a new shell process inside the container, giving you SSH-like access to the filesystem, environment, and processes. You can explicitly specify if no shell is needed when executing a command.

You can only access the shell and execute commands on a running service or job. You can specify the container to access, otherwise a running container will be selected at random.

Your commands will be executed in the container by the user specified in the Dockerfile used to build the image. If the Dockerfile does not specify a user, this will be the user set by the parent image (for example root for Alpine Linux). You can specify the default user in the Dockerfile with the USER instruction, for example USER northflank.

You can use northflank exec to run commands within your service and job containers via the CLI.

northflank exec service|job will let you select your project and service or job dynamically and then start a shell session directly in your container, similar to an SSH connection.

A command can also be specified directly which allows you to run a command without a shell:

northflank exec service|job --cmd "ls -lah"

There are multiple options such as instance, user and others which allow you to customise how commands are executed. You can view options with the northflank exec service|job --help command.

Modes

northflank exec service|job runs in one of three modes depending on the flags you pass:

• Interactive shell — northflank exec service. With no --cmd, an interactive session with stdin and TTY is opened. If --shell-cmd is not set, a list of standard shells is attempted in turn.
• Single command, no shell — northflank exec service --cmd 'date'. The command is executed directly inside the container without a shell, so shell features like pipes, redirects, globs, and $VAR expansion are not available.
• Single command, custom shell — northflank exec service --cmd 'ls -l /usr' --shell-cmd 'bash -c'. The command is passed to the specified shell, so shell expressions are evaluated.

Options

Execute a command as a specific user

You can execute your command as a specific user within the container by passing the --user <USER> option, where <USER> is the name or uid of the user to execute the command as.

For example, both the following commands will execute the command id as the root user:

$ northflank exec service --user root --cmd id
uid=0(root) gid=0(root) groups=0(root)
$ northflank exec service --user 0 --cmd id
uid=0(root) gid=0(root) groups=0(root)

Capturing output in non-interactive environments

northflank exec service|job --cmd '...' is designed for an interactive terminal. When stdout is not a TTY — for example in CI pipelines, automation harnesses, coding agents (such as Claude Code, OpenCode, etc), or under bash -c '...' — the remote command's stdout and stderr can be silently discarded. Neither --shell-cmd nor --verbose changes this. If you need to capture output programmatically, allocate a pseudo-TTY using script(1):

# macOS / BSD
script -q /dev/null northflank exec service --cmd 'ls -lah /workspace'

# Linux (util-linux)
script -qfc 'northflank exec service --cmd "ls -lah /workspace"' /dev/null

If you are scripting against Northflank from Node.js, prefer the JavaScript client's exec API, which returns stdout and stderr as readable streams without needing a PTY shim.

You can directly execute commands in your Northflank services and jobs with the JavaScript client.

The client exposes the exec module, which provides functionality to run commands.

Simple, short-lived command

You can run simple, short-lived commands which do not print a continuous stream of data with the following methods.

Execute a command in a service:

apiClient.exec.execServiceCommand({ projectId, serviceId }, { command: ['ls', '-lah'] })

Execute a command in a job:

apiClient.exec.execJobCommand({ projectId, jobId }, { command: ['ls', '-lah'] })

Options

Both methods return a promise with the result of the command in the format:

Promise<{
    commandResult: {
        exitCode: number;
        status: 'Success' | 'Failure' | 'Unknown';
        message?: string;
    };
    stdOut: string;
    stdErr: string;
}>

Execute a short-lived command as a specific user

You can execute your command as a specific user within the container by passing the user option, where the value is the name or uid of the user to execute the command as.

For example, both the following commands will execute the command id as the root user:

apiClient.exec.execServiceCommand({ projectId, serviceId }, { command: 'id', user: 'root' })
apiClient.exec.execServiceCommand({ projectId, serviceId }, { command: 'id', user: 0 })

Complex, long-running commands

You can execute long-running commands which print a continuous stream of data with the following methods, where options is a non-required object that can pass the arguments listed below.

Create an execute command session in a service:

await exec.execServiceSession({ projectId, serviceId }, { options });

Create an execute command session in a job:

await exec.execJobSession({ projectId, jobId }, { options });

Options

Session commands return a Promise of the ExecCommand class. This exposes a number of powerful functionalities to interact with the running command: Promise<ExecCommandStandard>.

You can write to and receive data from NodeJS-compatible streams for standard input, standard output and standard error.

For example:

const execCommand = await exec.execServiceSession({ projectId: 'myproject', serviceId: 'myservice' });

execCommand.stdErr.on('data', (chunk) => console.log(chunk));
// Locally logs chunks of data from your remote service to the console

execCommand.stdIn.write('echo "hello world"');
// Executes on your remote service and prints 'hello world'

To wait for command completion, run await execCommand.waitForCommandResult());. This will return a command result with exitCode and status, similar to execServiceCommand .

Execute a long-running command as a specific user

You can create a command session as a specific user within the container by passing the user option, where the value is the name or uid of the user to execute the command as. Any commands passed to the write stream will be executed as the user.

For example, both the following will execute any commands written to the stream as the root user:

const execCommand = await exec.execServiceSession({ projectId, serviceId }, { user: 'root' });
const execCommand = await exec.execServiceSession({ projectId, serviceId }, { user: 0 });