---
title: Unity CLI security and best practices
product: Unity command-line interface (CLI)
canonical: https://docs.unity.com/en-us/unity-cli/unity-cli-security
last_updated: 2026-11-16
generated_at: 2026-11-17T10:15:11.851Z
locale: en-us
---

# Unity CLI security and best practices

> Learn how the Unity CLI and the Unity Pipeline package control access to the Unity Editor, and follow best practices to use them safely with automation and AI agents.

The Unity CLI and the Unity Pipeline package give you programmatic control of your local Unity Editor. This page explains how these tools run code on your machine, how authentication protects access, how the `eval` command works, how the Unity Pipeline package behaves in Player builds, and how you can reduce security risks when you use them. It also covers workflows in which AI agents interact with the Unity Editor.

This page is for the following readers:

* Users of the Unity CLI or the Unity Pipeline package who want to understand their security boundaries.
* Users who connect AI agents or automation tools to the Unity Editor and want to limit their access.
* Security or IT teams that need to evaluate the Unity CLI before they approve it.

## Security model

The Unity CLI and the Unity Pipeline package are local developer tools. They run with the same permissions as your user account and operate within the same trust boundary as the Unity Editor.

When you install the Unity Pipeline package, the Unity Editor exposes two local endpoints that listen on the loopback address (`127.0.0.1`):

* HTTP API
* Pipeline protocol connection

The Unity CLI sends commands to these endpoints to control the Editor. Only your own machine can reach these endpoints. Other machines on your network can't send commands to the Editor unless you deliberately reconfigure your machine to expose the port. Don't expose the port because Unity doesn't support this configuration. The server also rejects requests from web pages, so a website you visit can't send commands to the Editor.

> **Important:**
>
> The server listens only on localhost in Unity Pipeline package 0.8.0 and later. Earlier versions listen on every network interface, although every request still requires the auth token.

Keep the following security principles in mind:

* Commands require authentication: The Editor rejects any command that lacks a valid token and returns a 401 error before it routes the request. The server generates the token when it starts and stores it in `Library/Pipeline/.unity-pipeline-port`, which is a file that only your user account can read. The token controls local access, not identity. Separately, the server binds to localhost, which blocks connections from other machines.
* Authentication controls who can call the Editor, not what a command does: The auth token prevents unauthenticated processes from sending commands to the Editor's local API. It doesn't restrict what an authenticated command can do, and it doesn't replace environment isolation or review of changes. After authentication, any tool that runs under your user account, such as the CLI, an AI agent you connect, or a script, operates with your full local permissions. Validate commands before you run them.
* The Unity Editor can always run code: When you open a Unity project, the Editor compiles and runs the C# code in that project. Editor scripts, packages, and assets can all run code. The Unity CLI doesn't add a new class of risk. It provides a programmatic interface to capabilities that the Editor already has.

> **Important:**
>
> Only open projects, install packages, and connect agents or tools that you trust. This guidance applies to all Unity Editor workflows, with or without the Unity CLI.

## The eval command and code execution

The `eval` command (`unity command script eval`) runs C# code in the connected Unity Editor. It's the foundation of agentic and automation workflows, because it lets tools perform operations that don't have a defined command yet.

The `eval` command doesn't change the security boundary. Like every other command, it requires authentication and runs with your user account's permissions. The Unity Editor already compiles and runs project code by design, so a process that can write a script into your project can run code without `eval`. The command adds convenience and speed, not new capability.

You can't disable the `eval` command. To reduce risk, isolate the environment and control which tools and AI agents you connect to the Editor. Disabling `eval` wouldn't help, because any process that can write a script into the project can run code in the Editor. For more information, refer to [Isolate the environment](#isolate-the-environment) and [Treat agent-connected sessions as privileged](#treat-agent-connected-sessions-as-privileged).

To remove `eval` from an AI agent's tool list, start the MCP server with the following command:

```bash
unity mcp --exclude-tools script eval
```

This option hides `eval` from the MCP client only. An agent that can run shell commands can still call `eval` directly.

## Control Pipeline access in Player builds

> **Important:**
>
> The Unity Pipeline package is an Editor and development tool. You should never enable the runtime server in a production build.

The Unity Pipeline package can expose its HTTP API in Player builds, so the CLI can drive a development build while it runs. For example, you can use this capability for automated playtests and live debug sessions.

The runtime server has the following safeguards:

* Disabled by default: Both settings in **Project Settings** > **Pipeline** > **Runtime** (**Enable in Development & Profiled Builds** and **Enable in Release Builds**) are disabled by default and work independently. When a build's setting is disabled, the build contains no Pipeline assemblies and no Roslyn compiler, so it can't run `eval` commands.
* Development and profiled builds: The build includes the runtime server only if you enable **Enable in Development & Profiled Builds**.
* Release builds: The build includes the runtime server and `eval` only if you enable **Enable in Release Builds**. The settings page shows a warning when you enable this setting.
* Localhost only: Like the Editor API, the runtime server accepts connections only from localhost. The runtime server isn't designed to accept connections from other machines.

Follow these practices for Player builds:

* Treat any build that has the runtime server enabled as a development artifact. Distribute it only to your team and QA, not to users.
* Keep **Enable in Release Builds** disabled for builds that you ship to users. To make sure that the build contains no Pipeline code, remove the Unity Pipeline package before you create a release build.
* Add a build validation step, such as a pre-build check or CI test, that fails the build if the `ENABLE_RUNTIME_PIPELINE` scripting define symbol appears in a release build's configuration.

## Best practices

Follow these practices to reduce risks when you use the Unity CLI, the Unity Pipeline package, or AI agents on your projects.

### Use version control and review changes

Follow these practices so you can review and revert changes when an agent or automation modifies your project:

* Keep your project in version control and work on a branch.
* Commit or stash your work before you start an agentic session, so you can revert cleanly.
* Review diffs before you merge changes from an agent, the same way you review changes from a human contributor.
* Don't let agents or automation push directly to protected branches.

### Isolate the environment

Run agentic and automated workflows in an environment that limits the impact of unintended actions:

* Use a copy or clone of the project, rather than your primary working copy, for exploratory agent sessions.
* On CI and build agents, run the CLI under a service account that has the minimum access it needs. Don't reuse personal credentials.
* Pass secrets through environment variables instead of command-line arguments, so they stay out of the process list. For example, provide the license serial for `unity license activate` through the `UNITY_LICENSE_SERIAL` environment variable.
* For full isolation, run agentic workflows in a virtual machine or on a dedicated machine with a copy of your project. Unity doesn't provide official container or Docker support for the Unity CLI.

### Limit credentials and secrets

Follow these practices to protect your credentials and secrets:

* Sign in with `unity auth login`, and let the CLI manage your session. The CLI keeps your sign-in in your operating system's secure credential storage (such as Credential Manager on Windows or Keychain on macOS).
* Don't paste tokens into scripts, agent prompts, or configuration files. When a script needs an access token, call `unity auth token` at runtime to get one.
* Run `unity auth logout` when you finish work on a shared or temporary machine.
* Keep API keys and project secrets out of the project folder. Any code that runs in the Editor can read files in the project, including code that an agent generates.

### Treat agent-connected sessions as privileged

When you connect an AI agent to the Unity Editor through the CLI, the agent can do anything you can do in the Editor, such as modifying assets, running code, and changing project settings. To reduce risk:

* Choose an agent client that supports approval prompts, and use the prompts to review the agent's proposed actions.
* Give the agent only the Editor tools it needs. Use the `--tools` and `--exclude-tools` options of `unity mcp` to limit the tools that an MCP client can see.
* Be cautious with untrusted content. Text inside assets, packages, or downloaded files can attempt to influence an agent's behavior. Only point agents at projects and content that you trust.
* Install plugins, skills, and packages only from sources that you trust. The CLI install scripts automatically configure your AI agents, which can add plugins and skills. To skip this step and install only the plugins and skills that you trust, set `UNITY_CLI_SKIP_SETUP=1`.
* Check where asset packages come from before you import them. unity assets inspect reports whether a package includes a signature attestation, and unity assets import --require-signed imports only packages that include one. These commands don’t verify the signature, so they don’t confirm that a package is authentic or unmodified. Verify the package’s source separately, and only import packages from publishers you trust.

### Prefer defined commands over eval command

When a defined command exists for an operation, use it instead of the `eval` command. Defined commands have predictable behavior and structured output, so it's easier to review and audit automation that uses them. To list the commands available in your project, run the following command. For more information, refer to [Run custom commands in the Unity CLI](/unity-cli/command-name-conventions/run-command-cli.md).

```bash
unity command
```

For operations that you repeat often, create a custom command in your project instead of running the same code through `eval` each time. A custom command has a stable name, defined inputs, and consistent behavior across sessions, which helps you, your team, and any connected agents. For more information, refer to [Define and name Unity CLI commands](/unity-cli/command-name-conventions/define-command.md).

## Report a security issue

To report a suspected vulnerability, use the [Unity Bug Bounty program](https://unity.com/security).

## Additional resources

* [Use the Unity CLI](/unity-cli/use-unity-cli.md)
* [Unity CLI reference](/unity-cli/reference.md)
* [Install Unity Pipeline package](/unity-cli/unity-pipeline/unity-pipeline-package.md)
* [Unity CLI data collection and privacy](/unity-cli/data-collection-privacy-controls.md)
