Skip to main content

​
Before you begin

If you want to manage Bnodes using the Brightnode CLI, you’ll need to install Brightnode CLI, and set your API key in the configuration. Run the following command, replacing BRIGHTNODE_API_KEY with your API key: 
brightnodectl config --apiKey BRIGHTNODE_API_KEY

​
Deploy a Bnode

You can deploy preconfigured Bnodes from the repos listed in the Brightnode Hub. For more info, see the Hub deployment guide.
  • Web
  • Command line
  • REST API
To create a Bnode using the Brightnode console:
  1. Open the Bnodes page in the Brightnode console and click the Deploy button.
  2. (Optional) Specify a network volume if you need to share data between multiple Bnodes, or to save data for later use.
  3. Select GPU or CPU using the buttons in the top-left corner of the window, and follow the configuration steps below.
GPU configuration:
  1. Select a graphics card (e.g., A40, RTX 4090, H100 SXM).
  2. Give your Bnode a name using the Bnode Name field.
  3. (Optional) Choose a Bnode Template such as Brightnode Pytorch 2.1 or Brightnode Stable Diffusion.
  4. Specify your GPU count if you need multiple GPUs.
  5. Click Deploy On-Demand to deploy and start your Bnode.
CUDA Version CompatibilityWhen using templates (especially community templates like Brightnode/pytorch:2.8.0-py3.11-cuda12.8.1-cudnn-devel-ubuntu22.04), ensure the host machine’s CUDA driver version matches or exceeds the template’s requirements.If you encounter errors like “OCI runtime create failed” or “unsatisfied condition: cuda>=X.X”, you need to filter for compatible machines:
  1. Click Additional filters in the Bnode creation interface
  2. Click CUDA Versions filter dropdown
  3. Select a CUDA version that matches or exceeds your template’s requirements (e.g., if the template requires CUDA 12.8, select 12.8 or higher)
Note: Check the template name or documentation for CUDA requirements. When in doubt, select the latest CUDA version as newer drivers are backward compatible.
CPU configuration:
  1. Select a CPU type (e.g., CPU3/CPU5, Compute Optimized, General Purpose, Memory-Optimized).
  2. Specify the number of CPUs and quantity of RAM for your Bnode by selecting an Instance Configuration.
  3. Give your Bnode a name using the Bnode Name field.
  4. Click Deploy On-Demand to deploy and start your Bnode.

​
Custom templates

Brightnode supports custom Bnode templates that let you define your environment using a Dockerfile. With custom templates, you can:
  • Install specific dependencies and packages.
  • Configure your development environment.
  • Create portable Docker images that work consistently across deployments.
  • Share environments with team members for collaborative work.

​
Stop a Bnode

If your Bnode has a network volume attached, it cannot be stopped, only terminated. When you terminate the Bnode, data in the /workspace directory will be preserved in the network volume, and you can regain access by deploying a new Bnode with the same network volume attached.
When a Bnode is stopped, data in the container disk is cleared, but data in the /workspace directory is preserved. To learn more about how Bnode storage works, see Storage overview. By stopping a Bnode you are effectively releasing the GPU on the machine, and you may be reallocated zero GPUs when you start the Bnode again.
After a Bnode is stopped, you will still be charged for its volume disk storage. If you don’t need to retain your Bnode environment, you should terminate it completely.
  • Web
  • Command line
To stop a Bnode:
  1. Open the Bnodes page.
  2. Find the Bnode you want to stop and expand it.
  3. Click the Stop button (square icon).
  4. Confirm by clicking the Stop Bnode button.

​
Stop a Bnode after a period of time

You can also stop a Bnode after a specified period of time. The examples below show how to use the CLI or web terminal to schedule a Bnode to stop after 2 hours of runtime.
  • Command line
  • Web terminal
Use the following command to stop a Bnode after 2 hours:
sleep 2h; brightnodectl stop bnode $BRIGHTNODE_POD_ID &
This command uses sleep to wait for 2 hours before executing the brightnodectl stop bnode command to stop the Bnode. The & at the end runs the command in the background, allowing you to continue using the SSH session.

​
Start a Bnode

Bnodes start as soon as they are created, but you can resume a Bnode that has been stopped.
  • Web
  • Command line
To start a Bnode:
  1. Open the Bnodes page.
  2. Find the Bnode you want to start and expand it.
  3. Click the Start button (play icon).

​
Terminate a Bnode

Terminating a Bnode permanently deletes all associated data that isn’t stored in a network volume. Be sure to export or download any data that you’ll need to access again.
  • Web
  • Command line
To terminate a Bnode:
  1. Open the Bnodes page.
  2. Find the Bnode you want to terminate and expand it.
  3. Stop the Bnode if it’s running.
  4. Click the Terminate button (trash icon).
  5. Confirm by clicking the Yes button.

​
View Bnode details

You can find a list of all your Bnodes on the Bnodes page of the web interface. If you’re using the CLI, use the following command to list your Bnodes: 
brightnodectl get bnode
Or use this command to get the details of a single Bnode: 
brightnodectl get bnode [POD_ID]

​
Access logs

Bnodes provide two types of logs to help you monitor and troubleshoot your workloads:
  • Container logs capture all output sent to your console standard output, including application logs and print statements.
  • System logs provide detailed information about your Bnode’s lifecycle, such as container creation, image download, extraction, startup, and shutdown events.
To view your logs, open the Bnodes page, expand your Bnode, and click the Logs button. This gives you real-time access to both container and system logs, making it easy to diagnose issues or monitor your Bnode’s activity.

​
Troubleshooting

Below are some common issues and solutions for troubleshooting Bnode deployments.

​
Zero GPU Bnodes

See Zero GPU Bnodes on restart.

​
Bnode stuck on initializing

If your Bnode is stuck on initializing, check for these common issues:
  1. You’re trying to SSH into the Bnode but didn’t provide an idle job like sleep infinity to keep it running.
  2. The Bnode received a command it can’t execute. Check your logs for syntax errors or invalid commands.
If you need help, contact support.

​
Docker daemon limitations

Brightnode manages the Docker daemon for you, which means you can’t run your own Docker instance inside a Bnode. This prevents you from building Docker containers or using tools like Docker Compose. To work around this, create a custom template with the Docker image you need.