Search and Replace

POST /v1/agents/runtime/{runtime_id}/files/replace Replaces every occurrence of a pattern across the files selected by path and glob. Like Find Files, the rewrite runs natively in the guest agent: there is no sed, no shell and no command injection surface. Each file is rewritten atomically. The new contents are written to a sibling temporary file, flushed to disk, given the original mode, owner and group, and then renamed over the original. A reader either sees the whole old file or the whole new file, never a partial one, and a crash mid-run cannot leave a truncated source file behind.

from gravixlayer import GravixLayer

client = GravixLayer()  # defaults to cloud="aws", region="us-east-1"
sandbox = client.runtime.create()  # defaults to template="base-small"

sandbox.file.write("/workspace/app.py", 'DB = "localhost:5432"\n')
sandbox.file.write("/workspace/pyproject.toml", 'version = "1.2.3"\n')

preview = sandbox.file.replace(
    "/workspace", "localhost:5432", "db.internal:5432",
    glob="*.py", dry_run=True,
)
for entry in preview:
    print(entry.path, entry.replacements)

# Then apply
result = sandbox.file.replace(
    "/workspace", "localhost:5432", "db.internal:5432", glob="*.py",
)
print(result.total_replacements, "across", len(result), "files")

# Regular expression with capture groups
sandbox.file.replace(
    "/workspace",
    r"version\s*=\s*\"([0-9.]+)\"",
    'version = "2.0.0"',
    glob="*.toml",
    regex=True,
)

sandbox.kill()

import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer(); // defaults to cloud="aws", region="us-east-1"
const sandbox = await client.runtime.create(); // defaults to template="base-small"

await sandbox.file.write('/workspace/app.py', 'DB = "localhost:5432"\n');
await sandbox.file.write('/workspace/pyproject.toml', 'version = "1.2.3"\n');

const preview = await sandbox.file.replace('/workspace', 'localhost:5432', 'db.internal:5432', {
  glob: '*.py',
  dryRun: true,
});
for (const entry of preview.files) {
  console.log(entry.path, entry.replacements);
}

const result = await sandbox.file.replace('/workspace', 'localhost:5432', 'db.internal:5432', {
  glob: '*.py',
});
console.log(result.totalReplacements, 'across', result.files.length, 'files');

await sandbox.file.replace(
  '/workspace',
  String.raw`version\s*=\s*"([0-9.]+)"`,
  'version = "2.0.0"',
  { glob: '*.toml', regex: true },
);

await sandbox.kill();

gravixlayer runtime files replace "$RT" /workspace "localhost:5432" "db.internal:5432" \
  --glob "*.py" --dry-run
gravixlayer runtime files replace "$RT" /workspace "localhost:5432" "db.internal:5432" \
  --glob "*.py"

curl -X POST "https://api.gravixlayer.ai/v1/agents/runtime/$RT/files/replace" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"/workspace","pattern":"localhost:5432","replacement":"db.internal:5432","glob":"*.py"}'

Parameters

Parameter	Type	Required	Description
`path`	string	Yes	Absolute directory to rewrite. A file path rewrites just that file
`pattern`	string	Yes	Text to replace. Must not be empty
`replacement`	string	Yes	Text to substitute. May be empty to delete matches
`glob`	string	No	Shell style name pattern such as `*.py`, limiting which files are rewritten
`regex`	boolean	No	Treat `pattern` as a regular expression and expand `$1` style groups in `replacement`. Defaults to `false`
`case_sensitive`	boolean	No	Match case exactly. Defaults to `false`
`include_hidden`	boolean	No	Descend into and rewrite dot-files. Defaults to `false`
`max_depth`	integer	No	Directory recursion limit. Defaults to 64, capped at 256
`dry_run`	boolean	No	Count replacements without writing anything. Defaults to `false`

Response

{
  "success": true,
  "files": [
    {"path": "/workspace/app.py", "replacements": 3},
    {"path": "/workspace/db/pool.py", "replacements": 1}
  ],
  "total_replacements": 4,
  "files_scanned": 137,
  "dry_run": false
}

Field	Type	Description
`files[].path`	string	Absolute path of a rewritten file
`files[].replacements`	integer	Occurrences replaced in that file
`total_replacements`	integer	Sum across every file
`files_scanned`	integer	Number of files examined
`dry_run`	boolean	Echoes the request flag; when `true` nothing was written

Files with zero occurrences are not listed and are not rewritten, so their mtime is untouched.

Behaviour notes

Literal by default. Without regex, both the pattern and the replacement are treated as plain text: $1 in the replacement stays $1, and no escaping is required.
Capture groups need regex. With regex: true, $1, $2 and ${name} in the replacement expand to the corresponding capture groups.
Metadata is preserved. Mode bits, owner and group are restored on the rewritten file, so a replace across a tree does not silently change permissions or ownership.
Binary and oversized files are skipped, using the same rules as Find Files: NUL byte sniff, UTF-8 validation and an 8 MiB ceiling.
Directory symlinks are never followed, so a link cannot be used to rewrite files outside path.
Dry run first for wide patterns. dry_run gives you the exact per-file counts the real run would produce, without touching the filesystem.

Getting Started

Runtime

Support

Parameters

Response

Behaviour notes

​Parameters

​Response

​Behaviour notes

Parameters

Response

Behaviour notes