Arcane.environment.set()

This focused page is derived from the mechanically checked full member inventory.

Syntax

Arcane.environment.set(name, value, options?)

Parameters

name: environment-variable name; value: string up to 32,767 characters generally, but a Linux protected value is limited by the 8,191-byte encoded Secret Service payload (about 6,126 ASCII value bytes); options.protected?: Boolean

Return value

Promise<{entry}>

Description

Creates or replaces a desktop user-scoped or Android app-scoped entry. Android rejects PATH; the SDK defaults sensitive-looking names to protected storage, and the returned protected value remains •••••. Requires environment.write and explicit application admission.

Overview

Creates or replaces one Arcane-managed environment entry. It is an exclusive, high-risk mutation available only to Vault with environment.write. Desktop hosts persist a user-scoped entry for future processes; Android persists an app-scoped entry in private storage. Already-running processes do not retroactively receive a desktop change.

Input and protection

Call set(name, value, options?). Values must be strings without null characters and generally may not exceed 32,767 characters. On Linux, protected Secret Service payloads have an additional 8,191-byte encoded ceiling (about 6,126 ASCII value bytes after metadata). options.protected must be a Boolean when supplied. The SDK defaults sensitive-looking names to protected storage, and Core refuses to save such names unprotected. On desktop, PATH must remain ordinary so future processes can use it; Android rejects any PATH mutation with ENVIRONMENT_PATH_UNSUPPORTED.

The promise resolves to {entry}. Protected results contain the ••••• mask, never an echo of the submitted secret.

Mutation uncertainty and recovery

Environment writes are serialized. ENVIRONMENT_OPERATION_BUSY, ENVIRONMENT_RECOVERY_REQUIRED, or ENVIRONMENT_SERIALIZATION_RELEASE_FAILED means the profile cannot safely accept another mutation yet. Linux can also report ENVIRONMENT_PROTECTED_CLEANUP_FAILED or ENVIRONMENT_METADATA_COMMIT_UNCERTAIN; Android can report ANDROID_ENVIRONMENT_STORAGE_UNCERTAIN. The renderer's normalized Arcane.Error currently exposes the public error code but not the native mutation-completion or cleanup-phase fields. Refresh the inventory after any of these uncertainty codes before deciding how to recover, and never blindly retry.

Example

async function saveSyntheticProtectedValue() {
    return Arcane.environment.set(
        'ARCANE_DEMO_TOKEN',
        'synthetic-development-value',
        { protected: true }
    );
}

document.querySelector('#confirm-environment-write')?.addEventListener(
    'click',
    async function handleConfirmedEnvironmentWrite() {
        const receipt = await saveSyntheticProtectedValue();
        console.log(receipt.entry.name, receipt.entry.protected);
    }
);

Reference group

Filesystem, storage, preferences, and appearance