We are happy to announce the general availability of LC's coding agent sandbox, Blackhole. This application allows for running Codex or Claude Code (or other) coding agents on LC systems safely and securely. For those of you currently using the MAPP sandbox, this sandbox is a direct replacement for the MAPP sandbox and the MAPP sandbox will be deprecated and removed in the coming weeks.

Why sandbox coding agents?

Coding agents can be very useful and increase the productivity of our users. But, as with all technology, there are risks associated with using them. Coding agents have been shown to perform tasks in unexpected ways; for example, deleting files without explicitly asking for permission. Likewise, it can take advantage of web services to perform tasks, which could involve uploading files to the internet unexpectedly. In order to both protect your files and prevent unintended distribution of files, the sandbox limits the coding agents to a well-defined set of filesystem directories and network addresses (URLs) that it can modify or access. Configuration files and command line arguments can add URLs (with OISSO approval) and other filesystem directories to the sandbox as needed. For more information, see https://lc.llnl.gov/confluence/spaces/LC/pages/909050205/Running+AI+Agents+on+LC .

Getting Started

To start using the sandboxed coding agents on LC systems, simply load the codex or claude modules and launch codex or claude, respectively. The wrapper scripts we have in place will guide you through any additional steps you need to get started, including copying a starting configuration file for the coding agent into your home directory.

Helpful Tips

  1. Create a dedicated space where you run these coding agents. In order to avoid giving the coding agents access to more code than you intended, create a directory in your home directory or workspace specifically for files that you've worked on with coding assistants. The sandbox expressly forbids running coding agents in the top level of your home directory (/g/g12/$USER) or your workspace directory (/usr/workspace/$USER), so creating a dedicated workspace for coding agents will help avoid the error invalid source path: not on allowlist: /g/g12/$USER.
  2. By default, the only URLs the coding agent can access are the API endpoints provided by LivAI or LLamaMe for serving the underlying AI models. If you require access to another URL, an exception can be made on a user or group basis by making a request to the OISSOs at lc-isso@llnl.gov and specifying the URL, the ports, and the username or group that requires access. Also include the machine or network on which you need this exception. Requesting for a unix group can help ensure that future members of the group get access automatically and reduces the number of duplicate requests your team has to submit.
  3. The sandbox has very little network access, so it is best practice to download everything you think you will need when you're running the coding agent. This can include cloning any code repositories, starting/building anything like a python virtual environment or spack environment for development, and anything else you may need to perform the task you hope to accomplish with the coding agent. Also, you can have a second terminal open outside of the sandbox and download anything you forgot. Just be vigilant that you understand what the coding agent is trying to download.

  4. In most cases, it is probably best to run your coding agent tasks in an existing allocation when using LC machines. You can also run with the --mpi mode on a compute node and run with single-node MPI parallelism for testing.