Skip to content

Puhti and Mahti computing services have been decommissioned. Puhti and Mahti login nodes and storage services will remain available until 15 October 2026, but are no longer covered by service contracts. Please clean up and migrate your data to Roihu ASAP. See Roihu data migration guide for instructions.

Agent environment

This page describes the containerized agent environment on Roihu, make sure you read the Must read section before usage, and follow the CSC AI Agent Policy.

Must read

Data privacy

By default, OpenCode is configured with the model provider OpenCode Zen, which is hosted by Anomaly Innovations, who maintain OpenCode. They provide a certain amount of use for free, but everything you type or the agent reads is sent to Anomaly Innovations and used according to their terms of service.

Claude Code and Codex send your prompts and the files the agent reads to Anthropic and OpenAI respectively. How that data is retained, and whether it may be used for model training, depends on the terms of the account you sign in with. CSC does not provide the endpoint and cannot determine this for you, so check the terms that apply to your own subscription before using Claude Code or Codex with confidential material.

  • Responsibility: You are always responsible for what your agent does. Every command it runs is executed under your personal account.
  • Security: The agent has access to the directory you launch it from, all of its subdirectories, and a few others for configurations. For the full list, see the repository. $HOME itself is not accessible by default.
  • Tool use: By default, the agent can use many read-only tools without permission, but asks for confirmation for any write operations. Check the repository for the full list of permissions.
  • Experimental status: The agent environment is still experimental and may change without notice.

How to use

To use OpenCode or Claude in your project directory, navigate to the directory and run the following commands:

module load roihu-agent-env

opencode
# or
claude
# or
codex

You can make additional directories visible in the environment with the --roihu-bind and --roihu-ro-bind flags when starting your agent. This works for all agents. --roihu-ro-bind only allows read-only access to the directory. An example:

claude --roihu-bind /path/to/dir1,/path/to/dir2

How to configure the agents

OpenCode

We recommend you use models hosted on Aitta, a CSC service.

Info

Only users with a LUMI project are able to access Aitta. We are working on providing access to everyone with a Roihu project.

Aitta is included in the default OpenCode configuration. You just need to get your API key from Aitta from the Generate token button, and save it to the $AITTA_KEY environment variable before you start the agent. 

export AITTA_KEY=<YOUR_KEY_HERE>
It is easiest to add this line to your ~/.bashrc so you don't have to set it every login.

If you want to use a different model provider, change tool permissions, or add MCP servers, you can add your configuration to ~/.config/opencode/opencode.json, or add an opencode.json with the configuration to your project directory. You can find instructions for custom configurations in the OpenCode documentation.

Claude Code

Aitta does not provide an Anthropic-compatible endpoint, so you cannot use it as an endpoint for Claude Code.

As with OpenCode, you can change settings with a JSON file, which you place at $HOME/roihu-claude/settings.json. Note that this path differs from the official path of $HOME/.claude/settings.json. This is done due to claude saving some things to ~/.claude.json, which would require binding $HOME. The custom directory allows us to avoid this. For the format and other details regarding settings and the configuration file, see the Claude Code documentation.

Alternatively you can change settings in Claude Code and the file will be auto-generated.

Codex

Codex does not support the endpoint format that Aitta provides, so you cannot use Aitta as an endpoint.

You can change settings and MCP servers in a config.toml placed in $HOME/roihu-codex. See the Codex docs for details on the exact format.

You can add MCP servers with the command

codex mcp add <server-name> --env VAR1=VALUE1 --env VAR2=VALUE2 -- <stdio server-command>

Any skills you want to add should be placed in the $HOME/roihu-codex/skills directory.

MCP servers

Model Context Protocol (MCP) is a standardized way for AI agents to access many different tools. See the MCP documentation for a general introduction.

The agent environment includes two MCP servers: one to run Slurm commands, and CSC-docs to search the CSC User Guide. You are free to add more.

Slurm

The agents are not able to run Slurm commands from within the container, the Slurm MCP server is the only route. It exposes a fixed set of commands and caches results, so repeated or redundant calls do not stress the Slurm database.

The MCP provides the following tools, listed with the underlying command each one runs. By default the agent can call the read-only tools without asking, while launch_job and cancel_job require your permission each time.

Tool Command Needs permission
my_jobs squeue --me No
job_history sacct No
sinfo sinfo No
batch_script scontrol write batch_script or sacct -B No
slurm_config scontrol show config No
reservations scontrol show reservations No
launch_job sbatch Yes
cancel_job scancel Yes

CSC-docs

The agents come preconfigured with the CSC-docs MCP server. You can read more about it in the CSC-docs MCP page.

Skills

Agent skills are markdown files which give an agent more context. They can provide the agents with workflows to follow, additional information, or ready-made scripts.

Skills are automatically invoked by the agent in situations it deems fit, which makes them token-efficient as they aren't read except the situations when they are needed. You can also manually invoke them by typing /<skill-name> at the start of your prompt for both OpenCode and Claude Code. You can read more about agent skills in the agent skills documentation.

The Roihu agent environment contains three skills by default: job-efficiency, software-environments, and batch-scripts. You can read more about them below.

Job efficiency

Fetches efficiency metrics for a job. If you don't give a Job ID, the agent works out which job you mean.

Software environments

Helps with installing or using software on Roihu. Checks whether something is already installed on Roihu, how to access it if it is, and what options for installation there are if it is not.

Batch scripts

Helps with batch/Slurm script creation, debugging, and optimization. Makes sure the script contains the necessary parts, takes into account some common cases (High I/O, MPI jobs, etc.) and what changes they require in the batch/Slurm script.

Adding your own skills

You can add your own skills for the agents. Create a skill according to the standards in the agent skills documentation, and add it to $HOME/.agents/skills for OpenCode, and to $HOME/roihu-claude/skills for Claude Code. Alternatively you can add the skills to the directory you launch the agents from in a .claude/skills folder instead of the aforementioned directories. Both Claude Code and OpenCode will check this directory. Skills placed in other locations than $HOME/.agents, $HOME/roihu-claude, or $HOME/roihu-codex will be scoped to the directory where they are placed.

You can find more skills created by CSC from our Github, which can help in the use other CSC services.