Environment files and secrets

Save environment variables in boxes.dev when your project's machines need the same configuration, such as an API key in .env.local. The saved values are kept in Project settings, and boxes.dev writes a copy into the file on your Template box and devboxes. When a value changes, edit it in Project settings: editing a machine's copy will not update the central values or any other machine.

If you have a Member project, a team admin defines the shared files and variable names, and you supply your own personal values and can add variables of your own; skip to Team and Member values for where to enter yours.

Add and review a file

For an independent project with its own Template box, register files through Project settings:

1. In the desktop app, open Project settings → Environment files → Add a file.
2. Select an existing file from your Template box and choose Add file. To create a file that doesn't exist yet, choose New file… and enter its folder and name.
3. For an existing file, review each recognized value. Choose Manage to save it in boxes.dev, Keep local to leave it in the file's local content below the managed section, or Remove to delete that assignment when management starts. For a new file, enter the variable names and values boxes.dev should manage.
4. Save the file. boxes.dev will write the managed values at the top of each machine's copy and preserve the local content below them.

boxes.dev syncs only the rows you manage. Content you keep local stays part of the file on the machine and reaches new devboxes with the rest of the snapshot's files.

You can select several files at once, then review and save each in turn. If you stop partway, files already saved will remain managed. Use Rescan if an existing file is missing from the list.

Return to the same page for later changes: open the managed file under Project settings → Environment files to edit saved values, add or remove managed rows, or stop managing an assignment, using the controls shown there. Machines update from what you save here.

Accepted names are .env, .env.*, *.env, .dev.vars, and .flaskenv — for example .env.local or config.env. A project's paths are relative to its project root: with one repository, the repository folder itself; with several, the folder that contains them. Team Template paths are relative to /home/boxes, with repository folders underneath it. Check the full location shown in the editor before saving. Paths through symbolic links and destinations that are not regular files are unsupported.

The initial import is a reviewed, one-time step. It recognizes simple, single-line assignments; comments, shell expressions, multiline values, and other unrecognized content stay local. If the file changes before the import finishes, boxes.dev will leave it alone and ask you to review it again. Later edits on a machine are never imported.

Add an environment file and review its values before saving. Select the image to enlarge it.

Understand the managed section

boxes.dev writes managed values at the start of the file, ending with:

# >>> BOXES_MANAGED_ENV_v1 <<<

The section above and including the marker is replaced during sync; content below it is preserved. Change managed values in Project settings — do not edit the managed section on the machine, and do not repeat a managed name below the marker to try to override it, because duplicate names are not a supported override mechanism.

Updates reach machines when they start or wake, usually within seconds of a saved change, and during a periodic retry about once a minute. Saving a value will not wake sleeping machines. If delivery is temporarily unavailable, the existing file stays in place and startup continues, so a new devbox may use the older copy from its snapshot until sync succeeds. A failed update to one file does not stop other files from syncing.

After a change, check that the file has updated, then restart your app if it reads environment variables only at startup.

Reveal, copy, or export values

Saved values are masked. Revealing a value, previewing or copying the managed file, and exporting it each need a fresh confirmation with the Google account linked to your boxes.dev account. The confirmation lasts five minutes in the current session; closing the editor, navigating away, switching accounts, signing out, or reaching the time limit will hide the revealed values again.

Values you haven't saved yet remain readable while you type or review them. Use Hide values during a screen share. boxes.dev keeps only the current saved value, with no per-value history, rollback, or recovery window.

Use Team and Member values

A team admin can define environment files in a Team Template, with two kinds of values:

• Team values are shared configuration supplied by the admin.
• Member values are personal configuration supplied by each member, such as their own API key. A required value must be entered before the member can create a project; a missing optional value is left out of the file.

An independent project receives its own copy of these definitions and values at creation, and later Team Template edits will not change that copy. A Member project follows the template's current definitions and Team values, while each member's personal values stay private to that member's project; team admins cannot read them through template management.

In a Member project, enter or replace your own values in Project settings → Environment files. A new required environment value does not block existing devboxes or agent startup.

To add a variable of your own, choose Add variable under a file, or Add a file to create a file just for your variables, then choose Save values. Your variables will reach all your devboxes in the project and no one else's. If your file has the same path as one of the team's files, both will be written to the same managed section. You can't add a name the team already sets in that file; if the team adds one of your names later, the team's value will be used and Project settings will ask you to rename or remove yours.

If an admin renames a Member value or moves it to another file, boxes.dev will omit the old value until you choose Use saved value here or enter a replacement; other values continue syncing. See Required member files and values.

Import a Team Template file

As a team admin, add files from the template's detail page under Environment and member files → Environment files. boxes.dev reads them from the template's latest saved version — or, before the first save, from your current editing session — and asks you to classify each recognized assignment as Team, Member, local, or removed before saving the import.

Each project applies that import decision once, including an existing Member project that receives a newly defined file. If a project's file has changed since your review, boxes.dev will add the managed section but preserve the existing content below it. That can leave a duplicate name for the project owner to remove from the local content.

Let an agent change variables

You can ask a coding agent to add, change, or remove variables for you. On a Template box, the agent can change the project's variables directly. On a devbox, it will first ask for access for its thread; see Let one thread edit your Template. Agents can't read saved values. For the commands, see Change environment variables.

Keep credentials appropriately scoped

Central values are encrypted, but authorized boxes.dev services can decrypt them for delivery and confirmed viewing; this is not end-to-end encryption. Delivered files are plaintext, and the project owner, root, processes, and agents on the machine can read them. Prefer development or narrowly scoped credentials over broad production ones.

Replacing a central value does not erase older copies in snapshots, backups, or running processes. Rotate or revoke the credential at its provider when that matters.

File limits

The limits are 64 KiB per value, 500 managed rows per file, 1 MiB for the rendered managed section, and 2 MiB for the initial reviewed import of an existing file. A larger file, or one that is not valid UTF-8, is preserved below the managed section instead of being imported.

New files are created with owner-only permissions. Existing files keep their current ownership and permissions.