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.
Read time 9 minutesLast updated 11 hours ago
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 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.
evalThis 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.
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 , 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.
Library/Pipeline/.unity-pipeline-port - 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.
The eval command and code execution
The command () 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.
evalunity command script evalThe 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 . The command adds convenience and speed, not new capability.
evalevalYou can't disable the command. To reduce risk, isolate the environment and control which tools and AI agents you connect to the Editor. Disabling 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 and Treat agent-connected sessions as privileged.
evalevalTo remove from an AI agent's tool list, start the MCP server with the following command:
evalunity mcp --exclude-tools script eval
This option hides from the MCP client only. An agent that can run shell commands can still call directly.
evalevalControl Pipeline access in Player builds
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 commands.
eval - 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 only if you enable Enable in Release Builds. The settings page shows a warning when you enable this setting.
eval - 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 scripting define symbol appears in a release build's configuration.
ENABLE_RUNTIME_PIPELINE
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 through the
unity license activateenvironment variable.UNITY_LICENSE_SERIAL - 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 , 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).
unity auth login - Don't paste tokens into scripts, agent prompts, or configuration files. When a script needs an access token, call at runtime to get one.
unity auth token - Run when you finish work on a shared or temporary machine.
unity auth logout - 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 and
--toolsoptions of--exclude-toolsto limit the tools that an MCP client can see.unity mcp - 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 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.
evalunity command
For operations that you repeat often, create a custom command in your project instead of running the same code through 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.
evalReport a security issue
To report a suspected vulnerability, use the Unity Bug Bounty program.