Skip to main content

Quickstart

Install Office and edit documents for free, with no sign-in or registration required. Use Editor SDK to control documents open in your browser directly from JavaScript. If you are developing an AI Agent, Editor AI SDK lets you add document editing capabilities to it.

Set up Office​

1. Run the container​

Install Docker and allocate at least 2 CPU cores and 4 GB of memory. Run the following command in your terminal to start an Office container with an included 30-day Trial license.

Free license for commercial use

A Free Commercial license is also available at no cost for commercial use. See the Free Commercial license guide for details.

docker run --name thinkfree-office-trial \
  -p 8080:8070 \
  thinkfree/office-single-node-trial:latest

Office initialization takes about 2 minutes, depending on your environment. Keep the terminal displaying the logs open and continue with the next steps in your browser.

2. Open a sample​

The container includes sample documents and a preconnected host-storage adapter. You can open a sample as soon as Office finishes initializing.

Open the following address in your browser. Clicking the link opens the sample document in a new tab.

http://localhost:8080/cloud-office/api/host-storage/sample.docx/open?app=WORD_EDITOR&user_id=local-user&docId=quickstart01 ↗

When the Word editor opens, you can edit the sample document.

3. Connect a document directory​

Stop the running container. Use the -v option as shown below to connect a document directory on your computer to /home/thinkfree/docs in the container.

docker run --name thinkfree-office-documents \
  -p 8080:8070 \
  -v "/absolute/path/to/documents:/home/thinkfree/docs" \
  thinkfree/office-single-node-trial:latest

Use the following URL format to open a document. Replace {relative-file-path} with the file path relative to your document directory.

http://localhost:8080/cloud-office/api/host-storage/{relative-file-path}/open?app=WORD_EDITOR&user_id=local-user&docId=quickstart01

For example, to open /absolute/path/to/documents/reports/proposal.docx on your computer, use the relative path reports/proposal.docx to build this URL.

http://localhost:8080/cloud-office/api/host-storage/reports/proposal.docx/open?app=WORD_EDITOR&user_id=local-user&docId=quickstart01 ↗

If file or folder names contain spaces or other characters that require URL encoding, encode each name separated by /.

Editor SDK​

Editor SDK lets you control documents that are open in your browser.

Add the following iframe to your application page.

<iframe
  id="office-frame"
  title="Thinkfree Office document"
  src="http://localhost:8080/cloud-office/api/host-storage/sample.docx/open?app=WORD_EDITOR&user_id=local-user&docId=quickstart01"
  style="width: 100%; height: 600px; border: 0;"
></iframe>

Editor SDK is publicly available on npm as @thinkfree.dev/tfo-sdk. Install it from your project directory.

npm install @thinkfree.dev/tfo-sdk

After installation, run the following JavaScript on the page containing the iframe above.

import { Office } from "@thinkfree.dev/tfo-sdk";

// Connect to the already-open Word editor.
const word = Office.word(document.querySelector("#office-frame"));
await word.whenReady();

// Read the document body.
const doc = word.getDocument();
const body = await doc.getBody();
console.log(await body.getText());

If the browser console displays the document body, the SDK connection and Editor SDK calls are working. Next, use the following code to add a paragraph and save.

// Append a paragraph without replacing existing text, then save.
await body.insertParagraph("Hello from Editor SDK", { position: "end" });
await doc.save();

On desktop Chrome/Edge, the following code opens the browser print dialog.

// Open printing. In desktop Chrome/Edge, choose "Save as PDF".
// This does not return PDF bytes or confirm that a file was saved.
await doc.print();

Call word.disconnect() to release the SDK connection when closing the application or leaving the editor screen.

Try SDK features in the Editor SDK Playground without installing Office. For more details, see the Editor SDK guide.

Editor AI SDK​

Editor AI SDK is publicly available on npm as @thinkfree.dev/tfo-ai-sdk. It requires Editor SDK, so install both packages.

npm install @thinkfree.dev/tfo-sdk @thinkfree.dev/tfo-ai-sdk

Editor AI SDK provides features that help an AI Agent use the Office editor. Use bridgeToolsViaSdk() to register Editor SDK Tools with your AI Agent integration. Each Tool includes a name, description, input schema, and execute(args). After the AI Agent selects a Tool, call its execute(args) to read or edit the Office document connected through Editor SDK.

Your AI Agent handles the model connection, conversation history, Tool selection, and permission checks. Editor AI SDK provides access to the Office document operations and executes them.

Implement askAgent, validateAndApprove, and returnToolResult in your AI Agent integration. Connect the Editor AI SDK functions to your agent workflow. The integration below keeps only the registered insert_text Tool for the AI Agent. The code comments describe Tool definitions and the response format.

import { bridgeToolsViaSdk } from "@thinkfree.dev/tfo-ai-sdk";

// Continue with the connected word handle from the Editor SDK section.
await word.whenReady();

const agentTools = new Map();
const toolBridge = await bridgeToolsViaSdk(word, {
  registerTool(tool) {
    // Expose only the tool approved for this task.
    if (tool.name === "insert_text") agentTools.set(tool.name, tool);
  },
  unregisterTool(name) { agentTools.delete(name); },
});
window.addEventListener("pagehide", () => toolBridge.unregisterAll());

// Customer-owned integration hooks, NOT Editor AI SDK methods:
// askAgent: send tools to your agent/model in its required schema format;
// normalize its response to { toolCalls: [{ id, name, args }] }.
// validateAndApprove: validate args against inputSchema, check permissions,
// and obtain any required user confirmation; reject by throwing an error.
// returnToolResult: return the result to the same agent conversation by call ID.
async function runAgentTurn({ askAgent, validateAndApprove, returnToolResult }) {
  const tools = [...agentTools.values()];
  const definitions = tools.map(({ name, description, inputSchema }) => ({
    name, description, inputSchema,
  }));

  // Your agent receives schemas, not JavaScript execute functions.
  // Its model chooses a tool and arguments; the SDK does not choose them.
  const response = await askAgent({
    instruction: "Insert a paragraph saying Hello from the agent.",
    tools: definitions,
  });

  for (const call of response.toolCalls ?? []) {
    const tool = tools.find((item) => item.name === call.name);
    if (!tool) throw new Error("Tool is not allowed: " + call.name);
    await validateAndApprove({ call, inputSchema: tool.inputSchema });

    // For an insert_text selection, this is that tool object's execute(args).
    // Editor AI SDK dispatches the call to the connected Office editor.
    const result = await tool.execute(call.args);

    // Preserve content/isError and the call ID so your agent can continue.
    await returnToolResult({ toolCallId: call.id, result });
  }
}
// Call runAgentTurn with your own three implementations.
// This example defines one turn; it does not create or run an AI agent.

For example, if the AI Agent returns insert_text and arguments, confirm that the Tool is allowed, validate the arguments, and call its execute(args). If the result contains isError, pass it back to the AI Agent without treating it as a success.

Try an AI Agent connected to Editor AI SDK in the Editor AI SDK Playground. For more details, see the Editor AI SDK guide.

Free Commercial license guide​

A Free Commercial license lets you use Office in commercial services at no cost. It supports 20 concurrent connections (MCC 20). The license is valid for 180 days and can be extended repeatedly. See Set up Office for application, download, and installation steps.