---
title: Scripts
description: A Script is saved Python automation for work you want to run again, run with different inputs, or schedule.
updated: 2026-09-12
canonical: https://turnpanel.com/docs/scripts
markdown: https://turnpanel.com/docs/scripts.md
llms: https://turnpanel.com/llms.txt
---

# Scripts

A Script is saved Python automation for work you want to run again, run with different inputs, or schedule.

## When to use a Script

Use a Script for repeatable work with files, data, reports, or services. Use a command for a one-time task. Use a Skill when the agent must make decisions during the procedure.


## How Scripts run

Each Script is a folder with main.py as its starting file. TurnPanel runs it with CPython 3.12. Inputs arrive in sys.argv[1:], and the Script cannot ask for terminal input. Only Python’s standard library and the turnpanel module are included automatically.


## TurnPanel APIs

- Use agent.ask when the Script needs AI judgment, mcp for connected services, and skills.load to read a Skill.
- Use state to remember progress between runs, runtime for information about the current run, and notify or log to show output.


## Dependencies

If a Script needs another Python package, include a fixed version inside the Script folder. Choose packages that work on macOS and Windows, and list what you added.


## Runs and safety

A Script can have only one active run. TurnPanel keeps the latest 1 MB of output and the 20 most recent runs. Exit code 0 marks a successful run.


### Output and stop controls

**Context:** Script run

The run panel shows live output, status, history, and Stop.

- **Output** [active]: Live standard output and standard error
- **Run history** [ready]: Select a dated run and status
- **Succeeded** [ready]: Exit code 0
- **Stop** [waiting]: Requests managed process-tree termination
- Scripts are not sandboxed. They can act with the same computer access as the signed-in user, subject to TurnPanel approvals.
- Save progress during long runs. Stopping may be immediate on Windows; macOS and Linux first ask the process and its children to exit, then force them if needed.
- Scheduling a Script lets it start later without asking again. Review anything that changes or sends data before turning on the schedule.